TypeScript DynamoDB

Este generador crea un nuevo proyecto TypeScript DynamoDB respaldado por Amazon DynamoDB, utilizando ElectroDB para el modelado de entidades con seguridad de tipos. Genera el código de aplicación y la infraestructura necesaria para aprovisionar y administrar una tabla DynamoDB utilizando AWS CDK o Terraform, con soporte para diseño de tabla única y desarrollo local integrado a través de DynamoDB Local.

Uso

Generar un Proyecto TypeScript DynamoDB

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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#dynamodb
5. Complete los parámetros requeridos
6. Haga clic en Generate

Opciones

Parámetro	Tipo	Predeterminado	Descripción
name Requerido	string	-	Nombre del proyecto DynamoDB a generar
directory	string	packages	El directorio donde almacenar el proyecto.
subDirectory	string	-	El subdirectorio donde se coloca el proyecto. Por defecto es el nombre del proyecto.
framework	electrodb	electrodb	El framework a utilizar para las entidades de DynamoDB.
tableName	string	-	El nombre de la tabla de DynamoDB. Se genera automáticamente si no se especifica.
infra	dynamodb | none	dynamodb	Infraestructura a aprovisionar para la tabla DynamoDB.
iac	inherit | cdk | terraform	inherit	El proveedor de IaC preferido. Por defecto, se hereda de tu selección inicial.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del Generador

El generador crea la siguiente estructura de proyecto en el directorio <directory>/<name>:

• Directoriosrc

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

    • example.ts Example ElectroDB entity definition
    • index.ts Entity exports
• config.json Table configuration including GSI definitions and local development settings
• package.json Project manifest defining the project’s package name and dependencies
• project.json Project configuration and build targets

Los scripts de desarrollo local se comparten entre todos los proyectos DynamoDB (tanto TypeScript como Python) y se generan una vez en:

• Directoriopackages/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

Infraestructura

Dado que este generador proporciona infraestructura como código basada en tu iac elegido, creará un proyecto en packages/common que incluye las construcciones CDK o módulos Terraform relevantes.

El proyecto común de infraestructura como código está estructurado de la siguiente manera:

CDK

• Directoriopackages/common/constructs

  • Directoriosrc

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

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

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

Proyecto Generado

Este proyecto se genera utilizando el generador ts#project y por lo tanto configura los mismos objetivos de compilación.

Terraform

• Directoriopackages/common/terraform

  • Directoriosrc

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

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

      • …
  • project.json Project build targets and configuration

Proyecto Generado

Este proyecto se genera utilizando el generador terraform#project y por lo tanto configura los mismos objetivos de compilación.

CDK

• Directoriopackages/common/constructs/src

  • Directorioapp

    • Directoriodynamodb

      • <name>.ts Infraestructura específica para tu tabla
  • Directoriocore

    • dynamodb.ts Construcción genérica de tabla DynamoDB

Terraform

• Directoriopackages/common/terraform/src

  • Directorioapp

    • Directoriodynamodb

      • Directorio<name>

        • <name>.tf Módulo específico para tu tabla
  • Directoriocore

    • Directoriodynamodb

      • dynamodb.tf Módulo genérico de DynamoDB

Desarrollo Local

Iniciar DynamoDB Local

El generador configura un target dev que inicia una instancia de DynamoDB Local y crea la tabla. Usa el target dev del proyecto:

pnpm

pnpm nx dev <project-name>

yarn

yarn nx dev <project-name>

npm

npx nx dev <project-name>

bun

bunx nx dev <project-name>

Esto automáticamente:

1. Descarga la imagen de DynamoDB Local (target pull-image)
2. Inicia un contenedor
3. Crea una tabla local con los índices definidos en config.json

Modelado de Datos

El proyecto generado utiliza ElectroDB para el modelado de entidades con seguridad de tipos en una sola tabla DynamoDB, siguiendo el diseño de tabla única de DynamoDB. Agrega o actualiza archivos de entidad en src/entities/, utilizando la entidad de ejemplo generada como punto de partida.

Ejemplo de definición de entidad:

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() },
  );

Para más detalles, consulta la documentación de entidades de ElectroDB.

Usar el Cliente DynamoDB

El archivo generado src/client.ts exporta dos utilidades clave:

• getDynamoDBClient() — devuelve un singleton en caché DynamoDBClient. Cuando LOCAL_DEV=true, se conecta a la instancia local de DynamoDB Local; de lo contrario, crea un cliente AWS utilizando la cadena de credenciales predeterminada.
• resolveTableName() — devuelve el nombre de la tabla DynamoDB. Cuando LOCAL_DEV=true, devuelve la constante del nombre de la tabla local; de lo contrario, obtiene el nombre de AWS AppConfig utilizando la variable de entorno RUNTIME_CONFIG_APP_ID y lo almacena en caché para llamadas posteriores.

Detener DynamoDB Local

Detener dev (por ejemplo, con Ctrl+C) elimina automáticamente el contenedor de DynamoDB Local, pero conserva el volumen nombrado para que tus datos persistan entre reinicios.

Windows

Debido a limitaciones con el manejo de señales en Windows, el contenedor no se elimina automáticamente cuando se detiene dev. Necesitarás eliminarlo manualmente:

<engine> rm -f <scope>-dynamodb

Reemplaza <engine> con tu motor de contenedores (docker o finch) y <scope> con el scope de tu espacio de trabajo Nx (por ejemplo, proj).

Agregar/Eliminar Índices Secundarios Globales

Los GSI se definen en config.json en la raíz del proyecto bajo la clave tableConfig.globalSecondaryIndexes. Agrega una entrada para cada GSI, siguiendo la convención de nomenclatura de diseño de tabla única para las claves GSI:

config.json

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

El campo sortKey es opcional para GSIs de solo clave hash.

Este archivo de configuración es la única fuente de verdad leída por todos los consumidores:

• Desarrollo local — dev lee config.json y crea o actualiza la tabla local para que coincida con la lista de GSI
• CDK — el constructo lee config.json en el momento de síntesis, por lo que los cambios de GSI se reflejan en el próximo cdk deploy
• Terraform — el módulo lee config.json en el momento de plan/apply

Un GSI por Despliegue

Precaución

DynamoDB no permite que se cree o elimine más de un GSI en una sola actualización de tabla.

Cada despliegue puede agregar o eliminar como máximo un GSI. Si necesitas agregar o eliminar múltiples GSIs, hazlo de uno en uno — actualiza config.json y las clases de entidad relevantes, despliega el stack, luego repite para el siguiente cambio.

Conectarse a la Tabla

En cualquier proyecto TypeScript, importa las fábricas de entidades de tu paquete DynamoDB y úsalas directamente:

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

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

Detrás de escena, createExampleEntity() llama a resolveTableName() para obtener el nombre de la tabla de AWS AppConfig en tiempo de ejecución.

Configuración en tiempo de ejecución

Esto depende de la variable de entorno RUNTIME_CONFIG_APP_ID para obtener la configuración de AWS AppConfig en tiempo de ejecución. Los proyectos construidos con este plugin (APIs, Agents, servidores MCP) ya tienen esta variable configurada automáticamente. Para otros proyectos, asegúrese de que RUNTIME_CONFIG_APP_ID esté establecida en el entorno de ejecución con el ID de aplicación de AppConfig aprovisionado por su infraestructura. Para más información, consulte la guía de Configuración en tiempo de ejecución.

Desplegar tu Tabla

El generador de DynamoDB crea infraestructura CDK o Terraform basada en tu iac seleccionado.

CDK

El constructo CDK se crea en common/constructs. Ejemplo de uso:

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');
  }
}

Esto aprovisiona una tabla de DynamoDB con:

• pk (clave de partición) y sk (clave de ordenamiento), ambas de tipo String
• Índices Secundarios Globales según se definen en config.json
• Facturación bajo demanda (PAY_PER_REQUEST)
• Cifrado KMS gestionado por el cliente con rotación automática de claves
• Recuperación point-in-time habilitada
• Protección contra eliminación habilitada
• Nombre de tabla registrado en Runtime Config bajo el espacio de nombres dynamodb en AWS AppConfig

Terraform

El módulo Terraform se crea en common/terraform. Ejemplo de uso:

packages/infra/src/main.tf

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

Esto aprovisiona una tabla de DynamoDB con:

• pk (clave de partición) y sk (clave de ordenamiento), ambas de tipo String
• Índices Secundarios Globales según se definen en config.json
• Facturación bajo demanda (PAY_PER_REQUEST)
• Cifrado KMS gestionado por el cliente con rotación automática de claves
• Recuperación point-in-time habilitada
• Protección contra eliminación habilitada
• Nombre de tabla registrado en Runtime Config

Protección contra Eliminación

La protección contra eliminación está habilitada por defecto para prevenir la eliminación accidental de la tabla.

Deshabilitar la Protección contra Eliminación

Deshabilítala para entornos donde se espera la eliminación de tablas, como stacks de desarrollo o preview de corta duración.

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
}

Modo de Facturación

La tabla usa por defecto facturación bajo demanda (PAY_PER_REQUEST). Cambia a capacidad aprovisionada para cargas de trabajo predecibles de alto rendimiento.

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"
}

Recuperación Point-in-time

La recuperación point-in-time está habilitada por defecto, permitiéndote restaurar la tabla a cualquier punto en los últimos 35 días.

Deshabilitar la Recuperación Point-in-time

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
}

Rotación de Clave de Cifrado

La clave KMS utilizada para cifrar la tabla tiene la rotación automática de claves habilitada por defecto. Deshabilítala si tu política de seguridad gestiona la rotación externamente.

Deshabilitar la Rotación de Clave de Cifrado

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
}

Conexiones

Utiliza el generador connection para integrar este proyecto con otros en tu espacio de trabajo. Las siguientes conexiones involucran este proyecto:

tRPC API to TypeScript DynamoDBConnect a tRPC API to a DynamoDB table

Smithy API to TypeScript DynamoDBConnect a Smithy API to a DynamoDB table

TypeScript Agent to TypeScript DynamoDBConnect a TypeScript Agent to a DynamoDB table

MCP Server to TypeScript DynamoDBConnect a TypeScript MCP Server to a DynamoDB table