@krypt0r/better-auth-dynamodb-adapter

A Better Auth adapter for DynamoDB using Single Table Design.

Features

• Single Table Design: Stores all Better Auth models (user, session, account, verification) in one DynamoDB table
• Optimized Queries: Uses a Global Secondary Index (GSI) for fast lookups by email, session token, and account provider
• Automatic TTL: Uses DynamoDB TTL to automatically clean up expired sessions and verification tokens
• Magic Link Support: Correctly indexes verification tokens by identifier for reliable magic link lookups
• TypeScript: Fully typed with Better Auth's type system

Installation

npm install @krypt0r/better-auth-dynamodb-adapter
# or
pnpm add @krypt0r/better-auth-dynamodb-adapter

Peer dependencies (install if not already present):

npm install better-auth @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

Usage

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";
import { dynamoDbAdapter } from "@krypt0r/better-auth-dynamodb-adapter";
import { betterAuth } from "better-auth";

const client = DynamoDBDocument.from(new DynamoDBClient({ region: "us-east-1" }), {
  marshallOptions: {
    convertEmptyValues: true,
    removeUndefinedValues: true,
    convertClassInstanceToMap: true,
  },
});

export const auth = betterAuth({
  database: dynamoDbAdapter({
    client,
    tableName: process.env.DYNAMODB_TABLE_NAME || "better-auth",
  }),
  // ... other Better Auth options
});

Configuration

interface DynamoDBAdapterConfig {
  client: DynamoDBDocument;      // Required: DynamoDB Document client
  tableName?: string;            // Default: "better-auth"
  partitionKey?: string;         // Default: "pk"
  sortKey?: string;              // Default: "sk"
  indexName?: string;            // Default: "GSI1"
  indexPartitionKey?: string;    // Default: "GSI1PK"
  indexSortKey?: string;         // Default: "GSI1SK"
  debugLogs?: DBAdapterDebugLogOption;
}

Table Schema

Create a DynamoDB table with:

| Attribute | Type | Role | |-----------|------|------| | pk | String | Partition key | | sk | String | Sort key | | GSI1PK | String | GSI partition key | | GSI1SK | String | GSI sort key | | expires | Number | TTL attribute |

The GSI (GSI1) should project all attributes.

Key Patterns

| Model | pk | sk | GSI1PK | GSI1SK | |-------|----|----|--------|--------| | User | USER#<id> | USER#<id> | USER#<email> | USER#<email> | | Session | SESSION#<id> | SESSION#<id> | SESSION#<token> | SESSION#<token> | | Account | USER#<userId> | ACCOUNT#<provider>#<accountId> | ACCOUNT#<provider>#<accountId> | ACCOUNT#<provider>#<accountId> | | Verification | VERIFICATION#<id> | VERIFICATION#<id> | VERIFICATION#<identifier> | VERIFICATION#<identifier> |

License

MIT