TypeScript DynamoDB

Ce générateur crée un nouveau projet TypeScript DynamoDB soutenu par Amazon DynamoDB, utilisant ElectroDB pour la modélisation d’entités type-safe. Il génère le code d’application et l’infrastructure nécessaires pour provisionner et gérer une table DynamoDB en utilisant AWS CDK ou Terraform, avec prise en charge de la conception à table unique et développement local intégré via DynamoDB Local.

Utilisation

Générer un projet 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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

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. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - ts#dynamodb
5. Remplissez les paramètres requis
6. Cliquez sur Generate

Options

Paramètre	Type	Par défaut	Description
name Requis	string	-	Nom du projet DynamoDB à générer
directory	string	packages	Le répertoire dans lequel stocker le projet.
subDirectory	string	-	Le sous-répertoire dans lequel le projet est placé. Par défaut, il s'agit du nom du projet.
framework	electrodb	electrodb	Le framework à utiliser pour les entités DynamoDB.
tableName	string	-	Le nom de la table DynamoDB. Généré automatiquement si non spécifié.
infra	dynamodb | none	dynamodb	Infrastructure à provisionner pour la table DynamoDB.
iac	inherit | cdk | terraform	inherit	Le fournisseur IaC préféré. Par défaut, celui-ci est hérité de votre sélection initiale.
preferInstallDependencies	boolean	true	Indique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir sur false pour différer l'installation lors de l'exécution de plusieurs générateurs en lot (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

Sortie du générateur

Le générateur crée la structure de projet suivante dans le répertoire <directory>/<name> :

• Répertoiresrc

  • index.ts Point d’entrée du projet et exports
  • client.ts Singleton du client DynamoDB et résolution du nom de table
  • Répertoireentities

    • example.ts Exemple de définition d’entité ElectroDB
    • index.ts Exports des entités
• config.json Configuration de la table incluant les définitions GSI et les paramètres de développement local
• package.json Manifeste du projet définissant le nom du package et les dépendances
• project.json Configuration du projet et cibles de build

Les scripts de développement local sont partagés entre tous les projets DynamoDB (TypeScript et Python) et générés une fois dans :

• Répertoirepackages/common/scripts/src/dynamodb

  • create-local-table.ts Crée la table DynamoDB dans l’instance DynamoDB Local locale
  • pull-image.ts Récupère l’image DynamoDB Local
  • start-container.ts Démarre le conteneur DynamoDB Local

Infrastructure

Étant donné que ce générateur fournit de l’infrastructure en tant que code basée sur votre iac choisi, il créera un projet dans packages/common qui inclut les constructs CDK ou modules Terraform pertinents.

Le projet d’infrastructure en tant que code commun est structuré comme suit :

CDK

• Répertoirepackages/common/constructs

  • Répertoiresrc

    • Répertoireapp/ Constructs pour l’infrastructure spécifique à un projet/générateur

      • …
    • Répertoirecore/ Constructs génériques qui sont réutilisés par les constructs dans app

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

Projet généré

Ce projet est généré en utilisant le générateur ts#project et configure donc les mêmes cibles de build.

Terraform

• Répertoirepackages/common/terraform

  • Répertoiresrc

    • Répertoireapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Répertoirecore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Projet généré

Ce projet est généré en utilisant le générateur terraform#project et configure donc les mêmes cibles de build.

CDK

• Répertoirepackages/common/constructs/src

  • Répertoireapp

    • Répertoiredynamodb

      • <name>.ts Infrastructure spécifique à votre table
  • Répertoirecore

    • dynamodb.ts Construct générique de table DynamoDB

Terraform

• Répertoirepackages/common/terraform/src

  • Répertoireapp

    • Répertoiredynamodb

      • Répertoire<name>

        • <name>.tf Module spécifique à votre table
  • Répertoirecore

    • Répertoiredynamodb

      • dynamodb.tf Module générique DynamoDB

Développement local

Démarrer DynamoDB Local

Le générateur configure une cible dev qui démarre une instance DynamoDB Local et crée la table. Utilisez la cible dev du projet :

pnpm

pnpm nx dev <project-name>

yarn

yarn nx dev <project-name>

npm

npx nx dev <project-name>

bun

bunx nx dev <project-name>

Cela effectue automatiquement :

1. Télécharge l’image DynamoDB Local (cible pull-image)
2. Démarre un conteneur
3. Crée une table locale avec les index définis dans config.json

Modélisation des données

Le projet généré utilise ElectroDB pour la modélisation d’entités type-safe sur une seule table DynamoDB, suivant la conception à table unique de DynamoDB. Ajoutez ou mettez à jour les fichiers d’entités sous src/entities/, en utilisant l’exemple d’entité généré comme point de départ.

Exemple de définition d’entité :

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

Pour plus de détails, consultez la documentation des entités ElectroDB.

Utiliser le client DynamoDB

Le fichier src/client.ts généré exporte deux utilitaires clés :

• getDynamoDBClient() — retourne un singleton DynamoDBClient en cache. Lorsque LOCAL_DEV=true, se connecte à l’instance DynamoDB Local locale ; sinon crée un client AWS utilisant la chaîne de credentials par défaut.
• resolveTableName() — retourne le nom de la table DynamoDB. Lorsque LOCAL_DEV=true, retourne la constante du nom de table locale ; sinon récupère le nom depuis AWS AppConfig en utilisant la variable d’environnement RUNTIME_CONFIG_APP_ID et le met en cache pour les appels suivants.

Arrêter DynamoDB Local

L’arrêt de dev (par exemple avec Ctrl+C) supprime automatiquement le conteneur DynamoDB Local, mais préserve le volume nommé afin que vos données persistent entre les redémarrages.

Windows

En raison de limitations dans la gestion des signaux sous Windows, le conteneur n’est pas automatiquement supprimé lorsque dev est arrêté. Vous devrez le supprimer manuellement :

<engine> rm -f <scope>-dynamodb

Remplacez <engine> par votre moteur de conteneurs (docker ou finch) et <scope> par la portée de votre espace de travail Nx (par exemple proj).

Ajouter/Supprimer des index secondaires globaux

Les GSI sont définis dans config.json à la racine du projet sous la clé tableConfig.globalSecondaryIndexes. Ajoutez une entrée pour chaque GSI, en suivant la convention de nommage de conception à table unique pour les clés GSI :

config.json

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

Le champ sortKey est optionnel pour les GSI avec clé de hachage uniquement.

Ce fichier de configuration est la source unique de vérité lue par tous les consommateurs :

• Développement local — dev lit config.json et crée ou met à jour la table locale pour correspondre à la liste des GSI
• CDK — le construct lit config.json au moment de la synthèse, donc les modifications de GSI sont reflétées lors du prochain cdk deploy
• Terraform — le module lit config.json au moment du plan/apply

Un GSI par Déploiement

Attention

DynamoDB n’autorise pas la création ou la suppression de plus d’un GSI lors d’une seule mise à jour de table.

Chaque déploiement peut ajouter ou supprimer au maximum un GSI. Si vous devez ajouter ou supprimer plusieurs GSI, faites-le un par un — mettez à jour config.json et les classes d’entité concernées, déployez la stack, puis répétez pour le changement suivant.

Se connecter à la table

Dans n’importe quel projet TypeScript, importez les factories d’entités depuis votre package DynamoDB et utilisez-les directement :

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

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

En coulisses, createExampleEntity() appelle resolveTableName() pour récupérer le nom de la table depuis AWS AppConfig au moment de l’exécution.

Configuration d’exécution

Cela repose sur la variable d’environnement RUNTIME_CONFIG_APP_ID pour récupérer la configuration depuis AWS AppConfig au moment de l’exécution. Les projets construits avec ce plugin (API, Agents, serveurs MCP) ont déjà cette variable configurée automatiquement. Pour les autres projets, assurez-vous que RUNTIME_CONFIG_APP_ID est définie dans l’environnement d’exécution avec l’ID d’application AppConfig provisionné par votre infrastructure. Pour plus d’informations, consultez le guide de configuration d’exécution.

Déployer votre table

Le générateur DynamoDB crée une infrastructure CDK ou Terraform en fonction de votre iac sélectionné.

CDK

Le construct CDK est créé dans common/constructs. Exemple d’utilisation :

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

Cela provisionne une table DynamoDB avec :

• pk (clé de partition) et sk (clé de tri), toutes deux de type String
• Des index secondaires globaux tels que définis dans config.json
• Une facturation à la demande (PAY_PER_REQUEST)
• Un chiffrement KMS géré par le client avec rotation automatique des clés
• La récupération à un instant donné activée
• La protection contre la suppression activée
• Le nom de la table enregistré dans Runtime Config sous l’espace de noms dynamodb dans AWS AppConfig

Terraform

Le module Terraform est créé dans common/terraform. Exemple d’utilisation :

packages/infra/src/main.tf

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

Cela provisionne une table DynamoDB avec :

• pk (clé de partition) et sk (clé de tri), toutes deux de type String
• Des index secondaires globaux tels que définis dans config.json
• Une facturation à la demande (PAY_PER_REQUEST)
• Un chiffrement KMS géré par le client avec rotation automatique des clés
• La récupération à un instant donné activée
• La protection contre la suppression activée
• Le nom de la table enregistré dans Runtime Config

Protection contre la suppression

La protection contre la suppression est activée par défaut pour empêcher la suppression accidentelle de la table.

Désactiver la protection contre la suppression

Désactivez-la pour les environnements où la suppression de table est attendue, comme les stacks de développement ou de prévisualisation éphémères.

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
}

Mode de facturation

La table utilise par défaut une facturation à la demande (PAY_PER_REQUEST). Passez à une capacité provisionnée pour des charges de travail prévisibles à haut débit.

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

Récupération à un instant donné

La récupération à un instant donné est activée par défaut, vous permettant de restaurer la table à n’importe quel moment des 35 derniers jours.

Désactiver la récupération à un instant donné

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
}

Rotation des clés de chiffrement

La clé KMS utilisée pour chiffrer la table a la rotation automatique des clés activée par défaut. Désactivez-la si votre politique de sécurité gère la rotation en externe.

Désactiver la rotation des clés de chiffrement

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
}

Connexions

Utilisez le générateur connection pour intégrer ce projet avec d’autres dans votre workspace. Les connexions suivantes impliquent ce projet :

tRPC API to TypeScript DynamoDBConnecter une API tRPC à une table DynamoDB

Smithy API to TypeScript DynamoDBConnecter une API Smithy à une table DynamoDB

TypeScript Agent to TypeScript DynamoDBConnecter un TypeScript Agent à une table DynamoDB

MCP Server to TypeScript DynamoDBConnecter un TypeScript MCP Server à une table DynamoDB