TypeScript DynamoDB

This generator creates a new TypeScript DynamoDB project backed by Amazon DynamoDB, using ElectroDB for type-safe entity modelling. It generates the application code and infrastructure needed to provision and manage a DynamoDB table using AWS CDK or Terraform, with single-table design support and built-in local development via DynamoDB Local.

Usage

Generate a TypeScript DynamoDB Project

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - ts#dynamodb
5. Fill in the required parameters
6. Click Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#dynamodb

yarn

yarn nx g @aws/nx-plugin:ts#dynamodb

npm

npx nx g @aws/nx-plugin:ts#dynamodb

bun

bunx nx g @aws/nx-plugin:ts#dynamodb

You can also perform a dry-run to see what files would be changed

pnpm

pnpm nx g @aws/nx-plugin:ts#dynamodb --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#dynamodb --dry-run

npm

npx nx g @aws/nx-plugin:ts#dynamodb --dry-run

bun

bunx nx g @aws/nx-plugin:ts#dynamodb --dry-run

Options

Parameter	Type	Default	Description
name Required	string	-	Name of the DynamoDB project to generate
directory	string	packages	The directory to store the project in.
subDirectory	string	-	The sub directory the project is placed in. By default this is the project name.
framework	electrodb	electrodb	The framework to use for DynamoDB entities.
tableName	string	-	The DynamoDB table name. Auto-generated if not specified.
infra	dynamodb | none	dynamodb	Infrastructure to provision for the DynamoDB table.
iac	inherit | cdk | terraform	inherit	The preferred IaC provider. By default this is inherited from your initial selection.
preferInstallDependencies	boolean	true	Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Generator Output

The generator creates the following project structure in the <directory>/<name> directory:

• Directorysrc

  • index.ts Project entry point and exports
  • client.ts DynamoDB client singleton and table name resolution
  • Directoryentities

    • example.ts Example ElectroDB entity definition
    • index.ts Entity exports
• config.json Table configuration including GSI definitions and local development settings
• project.json Project configuration and build targets

The local development scripts are shared across all DynamoDB projects (both TypeScript and Python) and generated once into:

• Directorypackages/common/scripts/src/dynamodb

  • create-local-table.ts Creates the DynamoDB table in the local DynamoDB Local instance
  • pull-image.ts Pulls the DynamoDB Local image
  • start-container.ts Starts the DynamoDB Local container

Infrastructure

Since this generator vends infrastructure as code based on your chosen iacProvider, it will create a project in packages/common which includes the relevant CDK constructs or Terraform modules.

The common infrastructure as code project is structured as follows:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Generated Project

This project is generated using the ts#project generator and therefore configures the same build targets.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Generated Project

This project is generated using the terraform#project generator and therefore configures the same build targets.

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directorydynamodb

      • <name>.ts Infrastructure specific to your table
  • Directorycore

    • dynamodb.ts Generic DynamoDB table construct

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorydynamodb

      • Directory<name>

        • <name>.tf Module specific to your table
  • Directorycore

    • Directorydynamodb

      • dynamodb.tf Generic DynamoDB module

Local Development

Starting Local DynamoDB

The generator configures a dev target that starts a DynamoDB Local instance and creates the table. Use the project’s dev target:

pnpm

pnpm nx dev <project-name>

yarn

yarn nx dev <project-name>

npm

npx nx dev <project-name>

bun

bunx nx dev <project-name>

This automatically:

1. Pulls the DynamoDB Local image (pull-image target)
2. Starts a container
3. Creates a local table with the indexes defined in config.json

Data Modelling

The generated project uses ElectroDB for type-safe entity modelling on a single DynamoDB table, following DynamoDB’s single-table design. Add or update entity files under src/entities/, using the generated example entity as a starting point.

Example entity definition:

packages/my-table/src/entities/example.ts

import { Entity } from 'electrodb';
import { getDynamoDBClient, resolveTableName } from '../client.js';

export const createExampleEntity = async () =>
  new Entity(
    {
      model: {
        entity: 'example',
        version: '1',
        service: 'MyTable',
      },
      attributes: {
        id: {
          type: 'string',
          required: true,
        },
        createdAt: {
          type: 'string',
          required: true,
          default: () => new Date().toISOString(),
          readOnly: true,
        },
        updatedAt: {
          type: 'string',
          required: true,
          default: () => new Date().toISOString(),
          watch: '*',
          set: () => new Date().toISOString(),
        },
      },
      indexes: {
        primary: {
          pk: {
            field: 'pk',
            composite: ['id'],
          },
          sk: {
            field: 'sk',
            composite: [],
          },
        },
      },
    },
    { client: getDynamoDBClient(), table: await resolveTableName() },
  );

For more details, see the ElectroDB entity documentation.

Using the DynamoDB Client

The generated src/client.ts exports two key utilities:

• getDynamoDBClient() — returns a cached singleton DynamoDBClient. When LOCAL_DEV=true, connects to the local DynamoDB Local instance; otherwise creates an AWS client using the default credential chain.
• resolveTableName() — returns the DynamoDB table name. When LOCAL_DEV=true, returns the local table name constant; otherwise fetches the name from AWS AppConfig using the RUNTIME_CONFIG_APP_ID environment variable and caches it for subsequent calls.

Stopping Local DynamoDB

Stopping dev (e.g. with Ctrl+C) automatically removes the DynamoDB Local container, but preserves the named volume so your data persists across restarts.

Windows

Due to limitations with signal handling on Windows, the container is not automatically removed when dev is stopped. You will need to remove it manually:

<engine> rm -f <scope>-dynamodb

Replace <engine> with your container engine (docker or finch) and <scope> with your Nx workspace scope (e.g. proj).

Adding/Removing Global Secondary Indexes

GSIs are defined in config.json at the project root under the tableConfig.globalSecondaryIndexes key. Add an entry for each GSI, following the single-table design naming convention for GSI keys:

config.json

{
  ...
  "tableConfig": {
    "globalSecondaryIndexes": [
      {
        "indexName": "gsi1pk-gsi1sk-index",
        "partitionKey": "gsi1pk",
        "sortKey": "gsi1sk"
      },
      {
        "indexName": "gsi2pk-gsi2sk-index",
        "partitionKey": "gsi2pk",
        "sortKey": "gsi2sk"
      }
    ]
  }
}

The sortKey field is optional for hash-key-only GSIs.

This config file is the single source of truth read by all consumers:

• Local development — dev reads config.json and creates or updates the local table to match the GSI list
• CDK — the construct reads config.json at synth time, so GSI changes are reflected on the next cdk deploy
• Terraform — the module reads config.json at plan/apply time

One GSI per Deployment

Caution

DynamoDB does not allow more than one GSI to be created or deleted in a single table update.

Each deployment can add or remove at most one GSI. If you need to add or remove multiple GSIs, do so one at a time — update config.json and relevant entity classes, deploy the stack, then repeat for the next change.

Connecting to the Table

In any TypeScript project, import entity factories from your DynamoDB package and use them directly:

import { createExampleEntity } from ':my-scope/my-table';

const entity = await createExampleEntity();
const result = await entity.query.primary({ id: '123' }).go();

Runtime config

When running in AWS, resolveTableName() fetches the table name from AWS AppConfig using the RUNTIME_CONFIG_APP_ID environment variable. Projects built with this plugin (tRPC APIs, Smithy APIs, agents, MCP servers) already have this variable configured automatically. For other TypeScript projects, ensure RUNTIME_CONFIG_APP_ID is set in the runtime environment with the AppConfig application ID provisioned by your infrastructure. For more information, see the Runtime Configuration guide.

Deploying your Table

The DynamoDB generator creates CDK or Terraform infrastructure based on your selected iac.

CDK

The CDK construct is created in common/constructs. Example usage:

packages/infra/src/stacks/application-stack.ts

import { MyTable } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const table = new MyTable(this, 'Table');
  }
}

This provisions a DynamoDB table with:

• pk (partition key) and sk (sort key), both String type
• Global Secondary Indexes as defined in config.json
• On-demand (PAY_PER_REQUEST) billing
• Customer-managed KMS encryption with automatic key rotation
• Point-in-time recovery enabled
• Deletion protection enabled
• Table name registered in Runtime Config under the dynamodb namespace in AWS AppConfig

Terraform

The Terraform module is created in common/terraform. Example usage:

packages/infra/src/main.tf

module "my_table" {
  source = "../../common/terraform/src/app/dynamodb/my-table"
}

This provisions a DynamoDB table with:

• pk (partition key) and sk (sort key), both String type
• Global Secondary Indexes as defined in config.json
• On-demand (PAY_PER_REQUEST) billing
• Customer-managed KMS encryption with automatic key rotation
• Point-in-time recovery enabled
• Deletion protection enabled
• Table name registered in Runtime Config

Granting Access

To allow Lambda functions to access the DynamoDB table, grant the necessary permissions in your infrastructure.

CDK

Call grantReadWriteData on the table construct. This grants both the DynamoDB and KMS permissions required by the Lambda execution role:

packages/infra/src/stacks/application-stack.ts

import { MyTable } from ':my-scope/common-constructs';

const table = new MyTable(this, 'Table');

const api = new Api(this, 'Api', {
  integrations: Api.defaultIntegrations(this).build(),
});

Object.entries(api.integrations).forEach(([, integration]) => {
  table.grantReadWriteData(integration.handler);
});

Note

This example grants every handler in your API access. If only some handlers need access, configure them individually.

Terraform

Grant the Lambda execution role permission to access the DynamoDB table and its KMS encryption key:

packages/infra/src/main.tf

module "my_table" {
  source = "../../common/terraform/src/app/dynamodb/my-table"
}

resource "aws_iam_role_policy" "dynamodb_access" {
  role = module.my_api.lambda_role_name

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = [
          "dynamodb:GetItem",
          "dynamodb:PutItem",
          "dynamodb:UpdateItem",
          "dynamodb:DeleteItem",
          "dynamodb:Query",
          "dynamodb:Scan",
          "dynamodb:BatchGetItem",
          "dynamodb:BatchWriteItem",
        ]
        Resource = [
          module.my_table.table_arn,
          "${module.my_table.table_arn}/index/*",
        ]
      },
      {
        Effect = "Allow"
        Action = [
          "kms:Encrypt",
          "kms:Decrypt",
          "kms:ReEncrypt*",
          "kms:GenerateDataKey*",
          "kms:DescribeKey"
        ]
        Resource = [module.my_table.kms_key_arn]
      },
    ]
  })
}

Deletion Protection

Deletion protection is enabled by default to prevent accidental table deletion.

Disable Deletion Protection

Disable it for environments where table deletion is expected, such as short-lived development or preview stacks.

CDK

packages/infra/src/stacks/application-stack.ts

import { MyTable } from ':my-scope/common-constructs';

const table = new MyTable(this, 'Table', {
  deletionProtection: false,
});

Terraform

packages/infra/src/main.tf

module "my_table" {
  source                      = "../../common/terraform/src/app/dynamodb/my-table"
  deletion_protection_enabled = false
}

Billing Mode

The table defaults to on-demand (PAY_PER_REQUEST) billing. Switch to provisioned capacity for predictable, high-throughput workloads.

CDK

packages/infra/src/stacks/application-stack.ts

import { BillingMode } from 'aws-cdk-lib/aws-dynamodb';
import { MyTable } from ':my-scope/common-constructs';

const table = new MyTable(this, 'Table', {
  billingMode: BillingMode.PROVISIONED,
  readCapacity: 5,
  writeCapacity: 5,
});

Terraform

packages/infra/src/main.tf

module "my_table" {
  source       = "../../common/terraform/src/app/dynamodb/my-table"
  billing_mode = "PROVISIONED"
}

Point-in-time Recovery

Point-in-time recovery is enabled by default, allowing you to restore the table to any point in the last 35 days.

Disable Point-in-time Recovery

CDK

packages/infra/src/stacks/application-stack.ts

import { MyTable } from ':my-scope/common-constructs';

const table = new MyTable(this, 'Table', {
  pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: false },
});

Terraform

packages/infra/src/main.tf

module "my_table" {
  source                         = "../../common/terraform/src/app/dynamodb/my-table"
  point_in_time_recovery_enabled = false
}

Encryption Key Rotation

The KMS key used to encrypt the table has automatic key rotation enabled by default. Disable it if your security policy manages rotation externally.

Disable Encryption Key Rotation

CDK

packages/infra/src/stacks/application-stack.ts

import { MyTable } from ':my-scope/common-constructs';

const table = new MyTable(this, 'Table', {
  enableKeyRotation: false,
});

Terraform

packages/infra/src/main.tf

module "my_table" {
  source              = "../../common/terraform/src/app/dynamodb/my-table"
  enable_key_rotation = false
}

Connections

Use the connection generator to integrate this project with others in your workspace. The following connections involve this project:

tRPC API to TypeScript DynamoDB Connect a tRPC API to a DynamoDB table

Smithy API to TypeScript DynamoDB Connect a Smithy API to a DynamoDB table

TypeScript Agent to TypeScript DynamoDB Connect a TypeScript Agent to a DynamoDB table

MCP Server to TypeScript DynamoDB Connect a TypeScript MCP Server to a DynamoDB table