diff --git a/docs/docs/reference/06-adapters/dynamodb.md b/docs/docs/reference/06-adapters/dynamodb.md deleted file mode 100644 index 617f3036..00000000 --- a/docs/docs/reference/06-adapters/dynamodb.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -id: dynamodb -title: DynamoDB ---- - -This is the AWS DynamoDB Adapter for `next-auth`. This package can only be used in conjunction with the primary `next-auth` package. It is not a standalone package. - -By default, the adapter expects a table with a partition key `pk` and a sort key `sk`, as well as a global secondary index named `GSI1` with `GSI1PK` as partition key and `GSI1SK` as sorting key. To automatically delete sessions and verification requests after they expire using [dynamodb TTL](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html) you should [enable the TTL](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/time-to-live-ttl-how-to.html) with attribute name 'expires'. You can set whatever you want as the table name and the billing method. - -You can find the full schema in the table structure section below. - -## Getting Started - -1. Install `next-auth`, `@next-auth/dynamodb-adapter`, `@aws-sdk/client-dynamodb` and `@aws-sdk/lib-dynamodb` - -```bash npm2yarn2pnpm -npm install next-auth @next-auth/dynamodb-adapter @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb -``` - -2. Add this adapter to your `pages/api/auth/[...nextauth].js` next-auth configuration object. - -You need to pass `DynamoDBDocument` client from the modular [`aws-sdk`](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/dynamodb-example-dynamodb-utilities.html) v3 to the adapter. -The default table name is `next-auth`, but you can customise that by passing `{ tableName: 'your-table-name' }` as the second parameter in the adapter. - -```javascript title="pages/api/auth/[...nextauth].js" -import { DynamoDB, DynamoDBClientConfig } from "@aws-sdk/client-dynamodb" -import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb" -import NextAuth from "next-auth"; -import Providers from "next-auth/providers"; -import { DynamoDBAdapter } from "@next-auth/dynamodb-adapter" - -const config: DynamoDBClientConfig = { - credentials: { - accessKeyId: process.env.NEXT_AUTH_AWS_ACCESS_KEY as string, - secretAccessKey: process.env.NEXT_AUTH_AWS_SECRET_KEY as string, - }, - region: process.env.NEXT_AUTH_AWS_REGION, -}; - -const client = DynamoDBDocument.from(new DynamoDB(config), { - marshallOptions: { - convertEmptyValues: true, - removeUndefinedValues: true, - convertClassInstanceToMap: true, - }, -}) - -export default NextAuth({ - // Configure one or more authentication providers - providers: [ - Providers.GitHub({ - clientId: process.env.GITHUB_ID, - clientSecret: process.env.GITHUB_SECRET, - }), - Providers.Email({ - server: process.env.EMAIL_SERVER, - from: process.env.EMAIL_FROM, - }), - // ...add more providers here - ], - adapter: DynamoDBAdapter( - client - ), - ... -}); -``` - -(AWS secrets start with `NEXT_AUTH_` in order to not conflict with [Vercel's reserved environment variables](https://vercel.com/docs/environment-variables#reserved-environment-variables).) - -## Schema - -The table respects the single table design pattern. This has many advantages: - -- Only one table to manage, monitor and provision. -- Querying relations is faster than with multi-table schemas (for eg. retrieving all sessions for a user). -- Only one table needs to be replicated if you want to go multi-region. - -> This schema is adapted for use in DynamoDB and based upon our main [schema](/reference/adapters/models) - -![DynamoDB Table](https://i.imgur.com/hGZtWDq.png) - -You can create this table with infrastructure as code using [`aws-cdk`](https://github.com/aws/aws-cdk) with the following table definition: - -```javascript title=stack.ts -new dynamodb.Table(this, `NextAuthTable`, { - tableName: "next-auth", - partitionKey: { name: "pk", type: dynamodb.AttributeType.STRING }, - sortKey: { name: "sk", type: dynamodb.AttributeType.STRING }, - timeToLiveAttribute: "expires", -}).addGlobalSecondaryIndex({ - indexName: "GSI1", - partitionKey: { name: "GSI1PK", type: dynamodb.AttributeType.STRING }, - sortKey: { name: "GSI1SK", type: dynamodb.AttributeType.STRING }, -}) -``` - -Alternatively, you can use this cloudformation template: - -```yaml title=cloudformation.yaml -NextAuthTable: - Type: "AWS::DynamoDB::Table" - Properties: - TableName: next-auth - AttributeDefinitions: - - AttributeName: pk - AttributeType: S - - AttributeName: sk - AttributeType: S - - AttributeName: GSI1PK - AttributeType: S - - AttributeName: GSI1SK - AttributeType: S - KeySchema: - - AttributeName: pk - KeyType: HASH - - AttributeName: sk - KeyType: RANGE - GlobalSecondaryIndexes: - - IndexName: GSI1 - Projection: - ProjectionType: ALL - KeySchema: - - AttributeName: GSI1PK - KeyType: HASH - - AttributeName: GSI1SK - KeyType: RANGE - TimeToLiveSpecification: - AttributeName: expires - Enabled: true -``` - -## Custom Schema - -You can configure your custom table schema by passing the `options` key to the adapter constructor: - -``` -const adapter = DynamoDBAdapter(client, { - tableName: "custom-table-name", - partitionKey: "custom-pk", - sortKey: "custom-sk", - indexName: "custom-index-name", - indexPartitionKey: "custom-index-pk", - indexSortKey: "custom-index-sk", -}) -``` diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 73329f64..322e8aef 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -284,6 +284,13 @@ const docusaurusConfig = { }, }, ], + [ + "docusaurus-plugin-typedoc", + { + ...typedocConfig, + ...createTypeDocAdapterConfig("DynamoDB"), + }, + ], [ "docusaurus-plugin-typedoc", { diff --git a/docs/package.json b/docs/package.json index 94c78824..22ee3e6f 100644 --- a/docs/package.json +++ b/docs/package.json @@ -23,6 +23,7 @@ "@next-auth/prisma-adapter": "workspace:*", "@next-auth/mongodb-adapter": "workspace:*", "@next-auth/typeorm-legacy-adapter": "workspace:*", + "@next-auth/dynamodb-adapter": "workspace:*", "@sapphire/docusaurus-plugin-npm2yarn2pnpm": "1.1.4", "classnames": "^2.3.2", "mdx-mermaid": "1.2.2", diff --git a/packages/adapter-dgraph/src/index.ts b/packages/adapter-dgraph/src/index.ts index 62b2c1fb..16f9d6af 100644 --- a/packages/adapter-dgraph/src/index.ts +++ b/packages/adapter-dgraph/src/index.ts @@ -1,18 +1,18 @@ /** *
- *

Official Dgraph adapter for Auth.js / NextAuth.js.

- * - * + *

Official DynamoDB adapter for Auth.js / NextAuth.js.

+ * + * * *
* * ## Installation * * ```bash npm2yarn2pnpm - * npm install next-auth @next-auth/dgraph-adapter + * npm install next-auth @next-auth/dynamodb-adapter @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb * ``` * - * @module @next-auth/dgraph-adapter + * @module @next-auth/dynamodb-adapter */ import { client as dgraphClient } from "./client" import { format } from "./utils" diff --git a/packages/adapter-dynamodb/src/index.ts b/packages/adapter-dynamodb/src/index.ts index b1f64b4d..fd147e57 100644 --- a/packages/adapter-dynamodb/src/index.ts +++ b/packages/adapter-dynamodb/src/index.ts @@ -1,3 +1,19 @@ +/** + *
+ *

Official Dgraph adapter for Auth.js / NextAuth.js.

+ * + * + * + *
+ * + * ## Installation + * + * ```bash npm2yarn2pnpm + * npm install next-auth @next-auth/dgraph-adapter + * ``` + * + * @module @next-auth/dgraph-adapter + */ import { v4 as uuid } from "uuid" import type { @@ -21,6 +37,139 @@ export interface DynamoDBAdapterOptions { indexSortKey?: string } +/** + * ## Basic usage + * + * This is the AWS DynamoDB Adapter for `next-auth`. This package can only be used in conjunction with the primary `next-auth` package. It is not a standalone package. + * By default, the adapter expects a table with a partition key `pk` and a sort key `sk`, as well as a global secondary index named `GSI1` with `GSI1PK` as partition key and `GSI1SK` as sorting key. To automatically delete sessions and verification requests after they expire using [dynamodb TTL](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html) you should [enable the TTL](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/time-to-live-ttl-how-to.html) with attribute name 'expires'. You can set whatever you want as the table name and the billing method. + * You can find the full schema in the table structure section below. + * + * ## Configuring `pages/api/auth/[...nextauth].js` + * + * You need to pass `DynamoDBDocument` client from the modular [`aws-sdk`](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/dynamodb-example-dynamodb-utilities.html) v3 to the adapter. + * The default table name is `next-auth`, but you can customise that by passing `{ tableName: 'your-table-name' }` as the second parameter in the adapter. + * + * ```javascript title="pages/api/auth/[...nextauth].js" + * import { DynamoDB, DynamoDBClientConfig } from "@aws-sdk/client-dynamodb" + * import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb" + * import NextAuth from "next-auth"; + * import Providers from "next-auth/providers"; + * import { DynamoDBAdapter } from "@next-auth/dynamodb-adapter" + * + * const config: DynamoDBClientConfig = { + * credentials: { + * accessKeyId: process.env.NEXT_AUTH_AWS_ACCESS_KEY as string, + * secretAccessKey: process.env.NEXT_AUTH_AWS_SECRET_KEY as string, + * }, + * region: process.env.NEXT_AUTH_AWS_REGION, + * }; + * + * const client = DynamoDBDocument.from(new DynamoDB(config), { + * marshallOptions: { + * convertEmptyValues: true, + * removeUndefinedValues: true, + * convertClassInstanceToMap: true, + * }, + * }) + * + * export default NextAuth({ + * // Configure one or more authentication providers + * providers: [ + * Providers.GitHub({ + * clientId: process.env.GITHUB_ID, + * clientSecret: process.env.GITHUB_SECRET, + * }), + * Providers.Email({ + * server: process.env.EMAIL_SERVER, + * from: process.env.EMAIL_FROM, + * }), + * // ...add more providers here + * ], + * adapter: DynamoDBAdapter( + * client + * ), + * ... + * }); + * ``` + * + * (AWS secrets start with `NEXT_AUTH_` in order to not conflict with [Vercel's reserved environment variables](https://vercel.com/docs/environment-variables#reserved-environment-variables).) + * + * ## Schema + * + * The table respects the single table design pattern. This has many advantages: + * + * - Only one table to manage, monitor and provision. + * - Querying relations is faster than with multi-table schemas (for eg. retrieving all sessions for a user). + * - Only one table needs to be replicated if you want to go multi-region. + * + * > This schema is adapted for use in DynamoDB and based upon our main [schema](/reference/adapters/models) + * + * ![DynamoDB Table](https://i.imgur.com/hGZtWDq.png) + * + * You can create this table with infrastructure as code using [`aws-cdk`](https://github.com/aws/aws-cdk) with the following table definition: + * + * ```javascript title=stack.ts + * new dynamodb.Table(this, `NextAuthTable`, { + * tableName: "next-auth", + * partitionKey: { name: "pk", type: dynamodb.AttributeType.STRING }, + * sortKey: { name: "sk", type: dynamodb.AttributeType.STRING }, + * timeToLiveAttribute: "expires", + * }).addGlobalSecondaryIndex({ + * indexName: "GSI1", + * partitionKey: { name: "GSI1PK", type: dynamodb.AttributeType.STRING }, + * sortKey: { name: "GSI1SK", type: dynamodb.AttributeType.STRING }, + * }) + * ``` + * + * Alternatively, you can use this cloudformation template: + * + * ```yaml title=cloudformation.yaml + * NextAuthTable: + * Type: "AWS::DynamoDB::Table" + * Properties: + * TableName: next-auth + * AttributeDefinitions: + * - AttributeName: pk + * AttributeType: S + * - AttributeName: sk + * AttributeType: S + * - AttributeName: GSI1PK + * AttributeType: S + * - AttributeName: GSI1SK + * AttributeType: S + * KeySchema: + * - AttributeName: pk + * KeyType: HASH + * - AttributeName: sk + * KeyType: RANGE + * GlobalSecondaryIndexes: + * - IndexName: GSI1 + * Projection: + * ProjectionType: ALL + * KeySchema: + * - AttributeName: GSI1PK + * KeyType: HASH + * - AttributeName: GSI1SK + * KeyType: RANGE + * TimeToLiveSpecification: + * AttributeName: expires + * Enabled: true + * ``` + * + * ## Configuring your custom schema + * + * You can configure your custom table schema by passing the `options` key to the adapter constructor: + * + * ``` + * const adapter = DynamoDBAdapter(client, { + * tableName: "custom-table-name", + * partitionKey: "custom-pk", + * sortKey: "custom-sk", + * indexName: "custom-index-name", + * indexPartitionKey: "custom-index-pk", + * indexSortKey: "custom-index-sk", + * }) + **/ export function DynamoDBAdapter( client: DynamoDBDocument, options?: DynamoDBAdapterOptions diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 0aa2b4bd..9c2419d9 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -225,6 +225,7 @@ importers: '@docusaurus/types': 2.2.0 '@mdx-js/react': 1.6.22 '@next-auth/dgraph-adapter': workspace:* + '@next-auth/dynamodb-adapter': workspace:* '@next-auth/firebase-adapter': workspace:* '@next-auth/mongodb-adapter': workspace:* '@next-auth/prisma-adapter': workspace:* @@ -247,6 +248,7 @@ importers: '@auth/sveltekit': link:../packages/frameworks-sveltekit '@mdx-js/react': 1.6.22_react@18.2.0 '@next-auth/dgraph-adapter': link:../packages/adapter-dgraph + '@next-auth/dynamodb-adapter': link:../packages/adapter-dynamodb '@next-auth/firebase-adapter': link:../packages/adapter-firebase '@next-auth/mongodb-adapter': link:../packages/adapter-mongodb '@next-auth/prisma-adapter': link:../packages/adapter-prisma