Skip to content

Commit

Permalink
style: format markdown files
Browse files Browse the repository at this point in the history
  • Loading branch information
thetutlage committed Jun 4, 2021
1 parent 037e4d4 commit eb8ca35
Show file tree
Hide file tree
Showing 3 changed files with 29 additions and 28 deletions.
1 change: 0 additions & 1 deletion .prettierignore
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
build
docs
*.md
config.json
.eslintrc.json
package.json
Expand Down
49 changes: 27 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,15 @@
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

## Table of contents

- [Ally custom driver boilerplate](#ally-custom-driver-boilerplate)
- [Getting started](#getting-started)
- [How is the code structured?](#how-is-the-code-structured)
- [YourDriverAccessToken](#yourdriveraccesstoken)
- [YourDriverScopes](#yourdriverscopes)
- [YourDriverConfig](#yourdriverconfig)
- [YourDriver](#yourdriver)
- [YourDriverAccessToken](#yourdriveraccesstoken)
- [YourDriverScopes](#yourdriverscopes)
- [YourDriverConfig](#yourdriverconfig)
- [YourDriver](#yourdriver)
- [Development checklist](#development-checklist)
- [Testing the driver](#testing-the-driver)
- [Release checklist](#release-checklist)
Expand All @@ -20,16 +21,18 @@
<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# Ally custom driver boilerplate

> A boilerplate for creating custom AdonisJS ally drivers
This repo serves as a starting point to create your custom OAuth2 drivers for [AdonisJS ally](https://docs.adonisjs.com/guides/auth/social).

The boilerplate is tailored to create one driver per project and publish it as a package on npm.

## Getting started

Following are the steps to get started.

- Fork this repo and then clone it on your local machine.
- Fork this repo and then clone it on your local machine.
- Install all the dependencies using `npm` or `yarn` (whatever you prefer).
- Open `package.json` file and update the package `name`, `description` and the `adonisjs` configuration block.

Expand All @@ -39,21 +42,21 @@ Following are the steps to get started.
"description": "",
"adonisjs": {
"types": "package-name",
"providers": [
"package-name"
]
"providers": ["package-name"]
}
}
```

## How is the code structured?

The code for the driver is inside the `src` directory. Make sure to change the `YourDriver` directory name to the name of the driver.

The driver implementation is mainly driven by the config, except the `user` and the `userFromToken` methods. Both of these methods are specific to the Oauth provider, and hence you have to implement them yourself.

The `src/YourDriver/index.ts` file has the following exports.

#### YourDriverAccessToken

The type defines the properties that exist on the access token returned by your driver. You must read your OAuth provider documentation and list all the properties here.

**Do not change the pre-defined `token` and `bearer` properties.**
Expand All @@ -66,9 +69,11 @@ export type YourDriverAccessToken = {
```
#### YourDriverScopes
Define a union of driver scopes accepted by your OAuth provider. You can check out the [official implementations](https://github.com/adonisjs/ally/blob/develop/adonis-typings/ally.ts#L236-L268) to see how they are defined.
#### YourDriverConfig
The type defines the configuration options that your driver expects. It must specify the following mentioned properties, along with any additional properties your driver needs to be functional.
```ts
Expand All @@ -84,6 +89,7 @@ export type YourDriverConfig = {
```
#### YourDriver
The driver implementation is a standard TypeScript class that extends the base `Oauth2Driver` class. The base driver class enforces you to define the following instance properties.
- `authorizeUrl` is the URL for the redirect request. The user is redirected to this URL to authorize the request. Check out provider docs to find this URL.
Expand Down Expand Up @@ -124,17 +130,17 @@ You can test the driver by installing it locally inside your AdonisJS applicatio
- Run `node ace configure <package-name>`. The configure command needs the package name and not the package path.
- Inform typescript about your driver by defining a mapping inside the `contracts/ally.ts` file.
```ts
import { YourDriverConfig, YourDriver } from 'ally-custom-driver/build/standalone'
interface SocialProviders {
yourDriver: {
config: YourDriverConfig,
implementation: YourDriver
}
}
```
```ts
import { YourDriverConfig, YourDriver } from 'ally-custom-driver/build/standalone'

interface SocialProviders {
yourDriver: {
config: YourDriverConfig
implementation: YourDriver
}
}
```

- Define the config inside the `config/ally.ts` file.
- And now you can use your driver like any other inbuilt driver.

Expand All @@ -157,8 +163,7 @@ You can configure the redirect request by implementing the `configureRedirectReq
protected configureRedirectRequest(request: RedirectRequest<YourDriverScopes>) {
request.param('key', 'value')
}
```

```

### How do I define extra fields/params for the access token request?

Expand All @@ -176,4 +181,4 @@ protected configureAccessTokenRequest(request: ApiRequest) {

## Share with others

Are you excited about sharing your work with others? Make sure to submit your package to the [awesome-adonisjs](https://github.com/adonisjs-community/awesome-adonisjs) repo.
Are you excited about sharing your work with others? Make sure to submit your package to the [awesome-adonisjs](https://github.com/adonisjs-community/awesome-adonisjs) repo.
7 changes: 2 additions & 5 deletions instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,7 @@ The package has been configured successfully!
Make sure to first define the mapping inside the `contracts/ally.ts` file as follows.

```ts
import {
YourDriver,
YourDriverConfig
} from 'ally-custom-driver/build/standalone'
import { YourDriver, YourDriverConfig } from 'ally-custom-driver/build/standalone'

declare module '@ioc:Adonis/Addons/Ally' {
interface SocialProviders {
Expand All @@ -17,4 +14,4 @@ declare module '@ioc:Adonis/Addons/Ally' {
}
}
}
```
```

0 comments on commit eb8ca35

Please sign in to comment.