DEV Community: Johannes Konings

CDK Mixin for Deletion Protection

Johannes Konings — Mon, 30 Mar 2026 20:00:02 +0000

Introduction

This post builds on the AWS CDK Ephemeral Stacks Cleanup pattern and focuses on permanent environments.

For permanent stacks, the goal is to couple CDK removal policies with CloudFormation deletion protection so critical resources are harder to delete by accident.

Mixin

A CDK mixin applies cross-cutting behavior across many constructs from one place.

This DeletionProtectionMixin sets stack-level termination protection and, for selected CloudFormation resources, enables deletion protection only when a retain-style removal policy is present.

The mapping in applyTo follows CloudFormation property names:

Stack.terminationProtection for stacks
deletionProtectionEnabled for AWS::Logs::LogGroup and AWS::DynamoDB::Table
deletionProtection for supported RDS, DocumentDB, and Neptune resources

By checking hasRetainRemovalPolicy first, the mixin keeps lifecycle intent aligned: resources marked to be retained also get deletion-protection settings where the service supports them.

import { CfnDeletionPolicy, CfnResource, Mixin, Stack } from "aws-cdk-lib";
import * as docdb from "aws-cdk-lib/aws-docdb";
import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
import * as logs from "aws-cdk-lib/aws-logs";
import * as neptune from "aws-cdk-lib/aws-neptune";
import * as rds from "aws-cdk-lib/aws-rds";
import type { IConstruct } from "constructs";

const hasRetainRemovalPolicy = (resource: CfnResource): boolean => {
  const { deletionPolicy, updateReplacePolicy } = resource.cfnOptions;
  return (
    deletionPolicy === CfnDeletionPolicy.RETAIN ||
    deletionPolicy === CfnDeletionPolicy.RETAIN_EXCEPT_ON_CREATE ||
    updateReplacePolicy === CfnDeletionPolicy.RETAIN ||
    updateReplacePolicy === CfnDeletionPolicy.RETAIN_EXCEPT_ON_CREATE
  );
};

export class DeletionProtectionMixin implements Mixin {
  public supports(construct: IConstruct): boolean {
    return (
      construct instanceof Stack ||
      construct instanceof logs.CfnLogGroup ||
      construct instanceof dynamodb.CfnTable ||
      construct instanceof rds.CfnDBCluster ||
      construct instanceof rds.CfnDBInstance ||
      construct instanceof rds.CfnGlobalCluster ||
      construct instanceof docdb.CfnDBCluster ||
      construct instanceof docdb.CfnGlobalCluster ||
      construct instanceof neptune.CfnDBCluster
    );
  }

  public applyTo(construct: IConstruct): IConstruct {
    if (construct instanceof Stack) {
      construct.terminationProtection = true;
      return construct;
    }

    if (!(construct instanceof CfnResource) || !hasRetainRemovalPolicy(construct)) {
      return construct;
    }

    if (construct instanceof logs.CfnLogGroup || construct instanceof dynamodb.CfnTable) {
      construct.deletionProtectionEnabled = true;
      return construct;
    }

    if (
      construct instanceof rds.CfnDBCluster ||
      construct instanceof rds.CfnDBInstance ||
      construct instanceof rds.CfnGlobalCluster ||
      construct instanceof docdb.CfnDBCluster ||
      construct instanceof docdb.CfnGlobalCluster ||
      construct instanceof neptune.CfnDBCluster
    ) {
      construct.deletionProtection = true;
    }

    return construct;
  }
}

/*
Known future expansion targets.

Top-level boolean-style deletionProtection:
AWS::RDS::DBCluster, AWS::RDS::DBInstance, AWS::RDS::GlobalCluster,
AWS::DocDB::DBCluster, AWS::DocDB::GlobalCluster, AWS::Neptune::DBCluster,
AWS::EKS::Cluster, AWS::QLDB::Ledger, AWS::NeptuneGraph::Graph

Top-level boolean-style deletionProtectionEnabled:
AWS::Logs::LogGroup, AWS::DynamoDB::Table, AWS::DSQL::Cluster,
AWS::SMSVOICE::PhoneNumber, AWS::SMSVOICE::Pool,
AWS::SMSVOICE::ProtectConfiguration, AWS::SMSVOICE::SenderId

Non-boolean mapping required:
AWS::Cognito::UserPool (ACTIVE|INACTIVE),
AWS::AutoScaling::AutoScalingGroup (none|prevent-force-deletion|prevent-all-deletion),
AWS::VerifiedPermissions::PolicyStore ({ mode: ENABLED|DISABLED })

Nested-only:
AWS::DynamoDB::GlobalTable.ReplicaSpecification.DeletionProtectionEnabled
*/

app

At the app boundary, lifecycle determines which global policy is applied:

Ephemeral stages use destroy-style cleanup behavior.
Permanent stages apply DeletionProtectionMixin so stacks and selected stateful resources gain deletion protection.

Applying the mixin once at App scope avoids repeating the same protection logic in every stack.

#!/usr/bin/env node
import { execSync } from 'node:child_process';
import { App, Mixins, RemovalPolicies, Tags } from 'aws-cdk-lib';
import { mixins as s3Mixins } from 'aws-cdk-lib/aws-s3';
import { DeletionProtectionMixin } from '../lib/mixins/DeletionProtection.ts';
// import { AwsSolutionsChecks, ServerlessChecks } from 'cdk-nag';
import {
  APPLICATION_RESOURCE_SCOPE_TAG_VALUE,
  RESOURCE_SCOPE_TAG_KEY,
} from '../lib/resource-tags.ts';
import { resolveStageLifecycle, resolveStageName } from '../lib/stage-name.ts';
import { TanstackAwsAuroraExpressDummyStack, TanstackAwsStack } from '../lib/tanstack-aws.ts';
import { WORKLOAD_REGION } from '../lib/workload-region.ts';

const workloadAccount = process.env.CDK_DEFAULT_ACCOUNT;

const app = new App();
Tags.of(app).add(RESOURCE_SCOPE_TAG_KEY, APPLICATION_RESOURCE_SCOPE_TAG_VALUE);

const resolveLocalGitBranch = (): string | undefined => {
  try {
    const branchName = execSync('git rev-parse --abbrev-ref HEAD', {
      encoding: 'utf8',
      stdio: ['ignore', 'pipe', 'ignore'],
    }).trim();
    return branchName && branchName !== 'HEAD' ? branchName : undefined;
  } catch {
    return undefined;
  }
};

const stageSource =
  process.env.APP_STAGE ??
  process.env.GITHUB_HEAD_REF ??
  process.env.GITHUB_REF_NAME ??
  resolveLocalGitBranch();

const appStage = resolveStageName(stageSource, {
  fallbackStage: 'dev',
  lifecycle: 'permanent',
});
const appLifecycle = resolveStageLifecycle(appStage);

// oxlint-disable-next-line no-console
console.log(`Deploying to stage: ${appStage} in region: ${WORKLOAD_REGION}`);

new TanstackAwsStack(app, `TanstackAwsStack-${appStage}`, {
  appStage,
  env: { account: workloadAccount, region: WORKLOAD_REGION },
});

...

if (appLifecycle === 'ephemeral') {
  RemovalPolicies.of(app).destroy();
  Mixins.of(app).apply(new s3Mixins.BucketAutoDeleteObjects());
} else if (appLifecycle === 'permanent') {
  Mixins.of(app).apply(new DeletionProtectionMixin());
} else {
  throw new Error(`Unknown appLifecycle: ${appLifecycle}`);
}

Result

Stack-level protection: termination protection is enabled for the permanent environment.

Log group protection: DeletionProtectionEnabled is set alongside retain-style lifecycle intent.

DynamoDB protection: table deletion protection is active for persistent data.

Conclusion

A deletion-protection mixin gives permanent environments a consistent baseline: enforce stack termination protection, then enable resource-level deletion protection only for supported services and only when retain-style policies indicate persistence intent. This centralization reduces configuration drift, keeps lifecycle behavior predictable during updates and deletes, and makes the policy easy to apply uniformly at app scope.

The boundary is intentional: not every CloudFormation resource exposes a native deletion-protection control, and some services require non-boolean or nested mappings. The safest extension path is to add resource types incrementally, document each property mapping explicitly, and keep the retain-policy gate so deletion protection remains aligned with lifecycle intent rather than applied indiscriminately.

Aspects and property injection were also valid options for this problem space. In practice, property injection is scoped per construct type rather than as one cross-resource mapping, while aspects are more naturally geared toward traversal, validation, and invariant checks than direct cross-service property manipulation.

Sources and References

Earlier pattern this post builds on: AWS CDK Ephemeral Stacks Cleanup
CDK mixins guide: Mixins - AWS CDK v2 Developer Guide
CDK aspects guide: Aspects - AWS CDK v2 Developer Guide
CDK blueprints and property injection: Configure constructs with CDK Blueprints - AWS CDK v2 Developer Guide
Stack termination protection: AWS CDK API Reference - StackProps.terminationProtection
CloudFormation deletion lifecycle: DeletionPolicy attribute
CloudFormation replacement lifecycle: UpdateReplacePolicy attribute
Dependency-injection tradeoffs: Inversion of Control Containers and the Dependency Injection pattern (Martin Fowler)
CloudWatch Logs deletion protection: AWS::Logs::LogGroup (DeletionProtectionEnabled)
DynamoDB deletion protection: AWS::DynamoDB::Table (DeletionProtectionEnabled)
RDS deletion protection: AWS::RDS::DBCluster (DeletionProtection), AWS::RDS::DBInstance (DeletionProtection), AWS::RDS::GlobalCluster (DeletionProtection)
DocumentDB deletion protection: AWS::DocDB::DBCluster (DeletionProtection), AWS::DocDB::GlobalCluster (DeletionProtection)
Neptune deletion protection: AWS::Neptune::DBCluster (DeletionProtection)

Aurora PostgreSQL Serverless (Express configuration) with CDK and Drizzle

Johannes Konings — Sat, 28 Mar 2026 20:03:16 +0000

Introduction

This post documents a setup for Aurora PostgreSQL express configuration with:

AWS CDK deployment
an AWS SDK-based custom resource (because CloudFormation support is not available yet)
Drizzle Kit and Drizzle Studio for schema and data verification

The setup is not production-ready, but it can be used as a starting point for further development.

AWS launch post:
Announcing Amazon Aurora PostgreSQL Serverless database creation in seconds

CDK Custom Resource

Aurora express configuration currently requires calling the RDS API directly. In this setup, CDK uses AwsCustomResource with CreateDBCluster and cleanup calls.

API reference:
CreateDBClusterCommand

import { Names, Stack } from "aws-cdk-lib";
import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
import {
  AwsCustomResource,
  AwsCustomResourcePolicy,
  PhysicalResourceId,
} from "aws-cdk-lib/custom-resources";
import { NagSuppressions } from "cdk-nag";
import { Construct } from "constructs";

export type DbAuroraExpressDummyProps = {
  databaseName: string;
  maxCapacity: number;
  minCapacity: number;
  schemaName: string;
};

const toIdentifier = (value: string, maxLength: number): string => {
  const normalized = value.toLowerCase().replace(/[^a-z0-9-]/g, "-");
  const compacted = normalized.replace(/-+/g, "-").replace(/^-|-$/g, "");
  if (compacted.length <= maxLength) {
    return compacted;
  }
  return compacted.slice(0, maxLength).replace(/-+$/g, "");
};

export class DbAuroraExpressDummy extends Construct {
  public readonly clusterArn: string;
  public readonly databaseName: string;
  public readonly schemaName: string;

  constructor(scope: Construct, id: string, props: DbAuroraExpressDummyProps) {
    super(scope, id);

    this.databaseName = props.databaseName;
    this.schemaName = props.schemaName;
    const minCapacity = props.minCapacity;
    const maxCapacity = props.maxCapacity;

    const stack = Stack.of(this);
    const baseIdentifier = toIdentifier(`${Names.uniqueId(this)}`, 63);
    // Aurora Express creates an instance identifier from the cluster identifier
    // (suffix like "-instance-1"), so keep the cluster id shorter than 63 chars.
    const clusterIdentifier = toIdentifier(`${baseIdentifier}-aurora`, 52);

    const instanceIdentifier = `${clusterIdentifier}-instance-1`;

    const clusterResource = new AwsCustomResource(this, "ExpressClusterFallback", {
      policy: AwsCustomResourcePolicy.fromStatements([
        new PolicyStatement({
          effect: Effect.ALLOW,
          actions: [
            "ec2:DescribeAvailabilityZones",
            "iam:CreateServiceLinkedRole",
            "rds:CreateDBCluster",
            "rds:CreateDBInstance",
            "rds:DeleteDBCluster",
            "rds:DeleteDBInstance",
            "rds:DescribeDBClusters",
            "rds:EnableInternetAccessGateway",
          ],
          resources: ["*"],
        }),
      ]),
      installLatestAwsSdk: true,
      onCreate: {
        action: "createDBCluster",
        service: "RDS",
        ignoreErrorCodesMatching: "DBClusterAlreadyExistsFault",
        physicalResourceId: PhysicalResourceId.of(clusterIdentifier),
        parameters: {
          DBClusterIdentifier: clusterIdentifier,
          Engine: "aurora-postgresql",
          WithExpressConfiguration: true,
          // Keep explicit ACU limits while using Aurora express defaults.
          ServerlessV2ScalingConfiguration: {
            MinCapacity: minCapacity,
            MaxCapacity: maxCapacity,
          },
        },
      },
      onUpdate: {
        action: "describeDBClusters",
        service: "RDS",
        physicalResourceId: PhysicalResourceId.of(clusterIdentifier),
        parameters: {
          DBClusterIdentifier: clusterIdentifier,
          Engine: "aurora-postgresql",
          WithExpressConfiguration: true,
          // Keep explicit ACU limits while using Aurora express defaults.
          ServerlessV2ScalingConfiguration: {
            MinCapacity: minCapacity,
            MaxCapacity: maxCapacity,
          },
        },
      },
      onDelete: {
        action: "deleteDBCluster",
        service: "RDS",
        ignoreErrorCodesMatching: "DBClusterNotFoundFault",
        parameters: {
          DBClusterIdentifier: clusterIdentifier,
          DeleteAutomatedBackups: true,
          SkipFinalSnapshot: true,
        },
      },
    });

    const clusterLookupResource = new AwsCustomResource(this, "ExpressClusterLookup", {
      policy: AwsCustomResourcePolicy.fromStatements([
        new PolicyStatement({
          effect: Effect.ALLOW,
          actions: ["rds:DescribeDBClusters"],
          resources: ["*"],
        }),
      ]),
      installLatestAwsSdk: true,
      onCreate: {
        action: "describeDBClusters",
        service: "RDS",
        physicalResourceId: PhysicalResourceId.of(`${clusterIdentifier}-lookup`),
        parameters: {
          DBClusterIdentifier: clusterIdentifier,
        },
      },
      onUpdate: {
        action: "describeDBClusters",
        service: "RDS",
        physicalResourceId: PhysicalResourceId.of(`${clusterIdentifier}-lookup`),
        parameters: {
          DBClusterIdentifier: clusterIdentifier,
        },
      },
    });
    clusterLookupResource.node.addDependency(clusterResource);

    const instanceCleanupResource = new AwsCustomResource(this, "ExpressInstanceCleanup", {
      policy: AwsCustomResourcePolicy.fromStatements([
        new PolicyStatement({
          effect: Effect.ALLOW,
          actions: ["rds:DeleteDBInstance", "rds:DescribeDBInstances", "rds:DescribeDBClusters"],
          resources: ["*"],
        }),
      ]),
      installLatestAwsSdk: true,
      onCreate: {
        action: "describeDBClusters",
        service: "RDS",
        physicalResourceId: PhysicalResourceId.of(`${clusterIdentifier}-instance-cleanup`),
        parameters: {
          DBClusterIdentifier: clusterIdentifier,
        },
      },
      onUpdate: {
        action: "describeDBClusters",
        service: "RDS",
        physicalResourceId: PhysicalResourceId.of(`${clusterIdentifier}-instance-cleanup`),
        parameters: {
          DBClusterIdentifier: clusterIdentifier,
        },
      },
      onDelete: {
        action: "deleteDBInstance",
        service: "RDS",
        ignoreErrorCodesMatching: "DBInstanceNotFoundFault|InvalidDBInstanceStateFault",
        parameters: {
          DBInstanceIdentifier: instanceIdentifier,
          DeleteAutomatedBackups: true,
          SkipFinalSnapshot: true,
        },
      },
    });
    instanceCleanupResource.node.addDependency(clusterResource);

    this.clusterArn = clusterLookupResource.getResponseField("DBClusters.0.DBClusterArn");
  }
}

Aurora deployment observations

From Aurora PostgreSQL express configuration documentation and deployment output:

The cluster is created without VPC association.
Internet access gateway is enabled for connectivity.
IAM authentication is required for gateway-based access.
Encryption uses an AWS/RDS managed key (a customer-managed KMS key cannot be selected at create time in this flow).
Data API is disabled by default at create time; it can be enabled later, with authentication constraints documented by AWS (Express configuration settings, enabling, usage and auth model). I have not managed to get Data API working with this express setup yet.

Teardown behavior

The custom resource includes explicit delete calls for both cluster and instance identifiers. During stack deletion, the cluster and instance cleanup sequence is visible in the AWS console. This is useful for ephemeral feature stacks where database infrastructure should be created and removed per branch or short-lived environment.

Drizzle integration

Drizzle is used for schema push, local studio inspection, and a simple seed script. Environment variables in this setup are managed with Varlock.

Varlock documentation

Drizzle ORM documentation

This setup was tested with the Drizzle beta track, which is expected to become v1 soon.

Required packages

Install these npm packages before running the examples:

Runtime dependencies: vp add @aws-sdk/rds-signer drizzle-orm pg varlock
Dev/tooling dependencies: vp add -D drizzle-kit @types/pg

Note: this repository uses Vite+, so commands in this post use vp wrappers (such as vp add, vp exec, and vp run) instead of direct npm or pnpm commands.

Configuration (`drizzle-kit`)

import { Signer } from "@aws-sdk/rds-signer";
import { defineConfig } from "drizzle-kit";
import { ENV } from "varlock/env";

const hostname = ENV.HOSTNAME;
const port = 5432;
const username = "postgres";
const database = "postgres";

const signer = new Signer({
  region: ENV.AWS_REGION,
  hostname,
  port,
  username,
});

const password = await signer.getAuthToken();

export default defineConfig({
  dialect: "postgresql",
  schema: "dummySchema.ts",
  dbCredentials: {
    host: hostname,
    port,
    user: username,
    password,
    database,
    ssl: true,
  },
});

Schema

import { integer, pgSchema, text } from "drizzle-orm/pg-core";

export const DUMMY_SCHEMA_NAME = "dummy";
export const dummySchema = pgSchema(DUMMY_SCHEMA_NAME);

export const dummyTable = dummySchema.table("dummy_table", {
  id: integer("id").primaryKey(),
  name: text("name").notNull(),
});

Run this command to apply schema changes:
vp exec varlock run -- vp exec drizzle-kit push --config=drizzle-user-password.config.ts

Run this command to open Drizzle Studio:
vp exec varlock run -- vp exec drizzle-kit studio --config=drizzle-user-password.config.ts

Studio before seeding (table exists, no rows):

Seeding script

#!/usr/bin/env node
/* oxlint-disable no-console */

import { Signer } from "@aws-sdk/rds-signer";
import { drizzle } from "drizzle-orm/node-postgres";
import { ENV } from "varlock/env";
import { dummyTable } from "../dummySchema.ts";

const hostname = ENV.HOSTNAME;
const port = 5432;
const username = "postgres";
const database = "postgres";

const signer = new Signer({
  region: ENV.AWS_REGION,
  hostname,
  port,
  username,
});

const password = await signer.getAuthToken();

console.log(ENV.HOSTNAME);
console.log(ENV.AWS_REGION);

const db = drizzle({
  connection: {
    host: hostname,
    port,
    user: username,
    password,
    database,
    ssl: true,
  },
});

await db.delete(dummyTable);

const insertResult = await db.insert(dummyTable).values([
  { id: 1, name: "Dummy 1" },
  { id: 2, name: "Dummy 2" },
  { id: 3, name: "Dummy 3" },
]);

console.log(insertResult);

vp exec varlock run -- node scripts/seed-dummy.ts

Result

Schema dummy.dummy_table is created successfully via Drizzle Kit.
Seed script inserts three rows (id 1..3).
Drizzle Studio confirms data visibility through the IAM-authenticated Aurora Express connection.

Conclusion

Aurora PostgreSQL express configuration can be integrated into a CDK workflow today by using AWS SDK custom resources for create/delete operations. Drizzle works with this setup when authentication tokens are generated through the RDS signer and passed to Drizzle tooling/runtime.

Sources and References

AWS announcement: Announcing Amazon Aurora PostgreSQL Serverless database creation in seconds
Aurora Express configuration docs: Creating and connecting to an Aurora PostgreSQL cluster with express configuration
RDS Data API enablement: Enabling the Amazon RDS Data API
RDS Data API usage/auth: Using the Amazon RDS Data API
RDS API (SDK v3): CreateDBClusterCommand
Varlock: varlock.dev
Drizzle ORM: orm.drizzle.team
Drizzle Kit: orm.drizzle.team/docs/drizzle-kit-overview

Tag log buckets created by AWS CDK for third party tools

Johannes Konings — Sun, 11 Jan 2026 08:15:18 +0000

Overview

How you secure cloud configuration often starts with cdk-nag, but many teams also use third-party tools after deployments. Using the “server access logs not configured” example, this post shows how cdk-nag can interact with those tools by tagging log buckets created by the AWS CDK.

This example focuses on the AwsSolutions-S1 rule from the AWS Solutions ruleset (https://github.com/cdklabs/cdk-nag/blob/main/RULES.md#awssolutions).

As of @jaykingson/cdk-nag-custom-nag-pack v0.0.11, this behavior is available via a log bucket tagger and an AwsSolutions-S1 suppression helper.

The cdk-nag log bucket behavior

If the log bucket and the source buckets are created in the same AWS CDK app, cdk-nag can identify that relationship and won’t raise AwsSolutions-S1 for the log bucket. If the app only provides the log bucket for usage outside the app, cdk-nag will raise AwsSolutions-S1.

The bridge to third party tools

If a third-party tool doesn’t check bucket dependencies and only checks whether the log bucket has server access logs enabled, it will still raise findings. One universal approach is to suppress those findings based on tags on the bucket itself.

The extension for cdk-nag to handle log bucket tagging

Because cdk-nag can identify the dependency within the app, it can also tag the log bucket to indicate that it is used for server access logs. e.g. isLogBucket=true and for better visibility an additional tag LogBucketTaggedBy=cdk-nag (or however you want the source to look).

The result

This app contains different usage patterns for log buckets and shows how the custom checks suppress and tag the log bucket.

TypeScript example

#!/usr/bin/env node
import { App, Aspects, Stack } from "aws-cdk-lib";
import {
  CustomChecks,
  CustomChecksSuppressions,
} from "@jaykingson/cdk-nag-custom-nag-pack";
import { Bucket } from "aws-cdk-lib/aws-s3";

const app = new App();

// Create two separate CloudFormation stacks to demonstrate cross-stack resource references
// Stack 1 will contain the primary log bucket and a test bucket
const stack = new Stack(app, "Stack");
// Stack 2 will demonstrate referencing log buckets from different stacks
const stack2 = new Stack(app, "Stack2");

// Create a dedicated log bucket that will serve as the central logging destination
// for other application buckets across the infrastructure
const logBucketForOtherAppsBuckets = new Bucket(
  stack,
  "LogBucketForOtherAppsBuckets",
  {
    enforceSSL: true,
  },
);
// Usage of the new supression, which also tag as an log bucket
CustomChecksSuppressions.addLogBucketS1Suppression(
  logBucketForOtherAppsBuckets,
);

// Reference an existing log bucket in Stack2 by its ARN (Amazon Resource Name)
// This demonstrates importing external resources that may already exist in your AWS account
const logBucketLookup = Bucket.fromBucketArn(
  stack2,
  "LogBucketLookup",
  "arn:aws:s3:::log-bucket-lookup",
);

// Create another log bucket in Stack 1 for demonstration purposes
// This bucket will also serve as a logging destination for application buckets
const logBucket = new Bucket(stack, "LogBucket", {
  enforceSSL: true,
});

// Create a test application bucket in Stack 1 that logs access to the local log bucket
// This demonstrates the standard pattern: application bucket → log bucket (same stack)
new Bucket(stack, "TestBucket", {
  enforceSSL: true,
  serverAccessLogsBucket: logBucket,
});

// Create a test bucket in Stack2 that references the imported log bucket
// This shows how buckets can log to external/imported logging destinations
new Bucket(stack2, "TestBucketLookup", {
  enforceSSL: true,
  serverAccessLogsBucket: logBucketLookup,
});

// Create another test bucket in Stack2, but this time referencing the log bucket from Stack 1
// This demonstrates CROSS-STACK resource references - a powerful CDK feature
// CDK automatically creates the necessary CloudFormation exports/imports
new Bucket(stack2, "TestBucket2", {
  enforceSSL: true,
  serverAccessLogsBucket: logBucket,
});

// Apply custom CDK Nag checks to the entire application using the Aspects pattern
// Aspects run validation rules against all resources in the app before synthesis
Aspects.of(app).add(
  new CustomChecks({
    enableAwsSolutionChecks: true, // Enable AWS Solutions construct library compliance checks
    enableLogBucketTagger: true, // Automatically tag log buckets for third-party security scanners
  }),
);

LogBucketForOtherAppsBucketsF118033B has the suppression and the tags applied, and LogBucketCC3B17E8 is treated as a log bucket because it is created and referenced within the app.

The synthesized CloudFormation template

CloudFormation template excerpt

{
 "Resources": {
  "LogBucketForOtherAppsBucketsF118033B": {
   "Type": "AWS::S3::Bucket",
   "Properties": {
    "Tags": [
     {
      "Key": "isLogBucket",
      "Value": "true"
     },
     {
      "Key": "LogBucketTaggedBy",
      "Value": "cdkNagCustomChecks"
     }
    ]
   },
   "UpdateReplacePolicy": "Retain",
   "DeletionPolicy": "Retain",
   "Metadata": {
    "aws:cdk:path": "Stack/LogBucketForOtherAppsBuckets/Resource",
    "cdk_nag": {
     "rules_to_suppress": [
      {
       "reason": "This is intended to be a log bucket. Log bucket does not require access logging to prevent infinite loop",
       "id": "AwsSolutions-S1"
      }
     ]
    }
   }
  },
 ...
  "LogBucketCC3B17E8": {
   "Type": "AWS::S3::Bucket",
   "Properties": {
    "Tags": [
     {
      "Key": "isLogBucket",
      "Value": "true"
     },
     {
      "Key": "LogBucketTaggedBy",
      "Value": "cdkNagCustomChecks"
     }
    ]
   },
   "UpdateReplacePolicy": "Retain",
   "DeletionPolicy": "Retain",
   "Metadata": {
    "aws:cdk:path": "Stack/LogBucket/Resource",
    "cdk_nag": {
     "rules_to_suppress": [
      {
       "reason": "This is intended to be a log bucket. Log bucket does not require access logging to prevent infinite loop",
       "id": "AwsSolutions-S1"
      }
     ]
    }
   }
  },
  ...
  "TestBucket560B80BC": {
   "Type": "AWS::S3::Bucket",
   "Properties": {
    "LoggingConfiguration": {
     "DestinationBucketName": {
      "Ref": "LogBucketCC3B17E8"
     }
    }
   },
   "UpdateReplacePolicy": "Retain",
   "DeletionPolicy": "Retain",
   "Metadata": {
    "aws:cdk:path": "Stack/TestBucket/Resource"
   }
  },
  ...
  "CDKMetadata": {
   "Type": "AWS::CDK::Metadata",
   "Properties": {
    "Analytics": "v2:deflate64:H4sIAAAAAAAA/0WISw5AMBBAz2LfDoYTcAHhAFJVySiVmJaIuLtFJVbvg4AFQp6ok6UerVxogLvzSluhTu65gLsK2hov6sl9FtFsC+nr37GfR7htNDBzemAJOUKWzEwk9+A8rQbayBeDG/QVeAAAAA=="
   },
   "Metadata": {
    "aws:cdk:path": "Stack/CDKMetadata/Default"
   },
   "Condition": "CDKMetadataAvailable"
  }
 },
 "Outputs": {
  "ExportsOutputRefLogBucketCC3B17E818DCEC53": {
   "Value": {
    "Ref": "LogBucketCC3B17E8"
   },
   "Export": {
    "Name": "Stack:ExportsOutputRefLogBucketCC3B17E818DCEC53"
   }
  }
 },
}

Sources and links

Using Server Sent Events (SSE) to sync Tanstack Db from AWS DynamoDB

Johannes Konings — Thu, 08 Jan 2026 08:15:18 +0000

Introduction

As described in Simple example of TanStack DB with DynamoDB on AWS with multiple entities, we set up a multi-entity data model using ElectroDB and TanStack DB collections. In this post, we will explore how to keep our TanStack DB in sync with AWS DynamoDB using Server Sent Events (SSE).

TanStack DB has the advantage that it can update specific database entries without needing to refetch all the data. This capability enables real-time synchronization across multiple sessions when another user or process modifies the data. Instead of polling the database constantly or refreshing entire datasets, SSE allows the server to push only the changes that occurred, making the application more efficient and responsive.

⚠️ Disclaimer : This implementation is somewhat hacky and is intended to prove the approach and demonstrate the concept. It has not been battle-tested in production environments and may contain errors or edge cases that haven't been fully addressed.

Demo Video

Architecture Overview

The synchronization architecture consists of three main components working together:

DynamoDB Streams : Captures all data changes from the main DynamoDB table
Event Table : Stores a change log of all modifications for historical tracking
SSE Endpoint : Streams these changes to connected clients in real-time

This architecture enables multiple clients to stay synchronized with minimal latency while maintaining a complete audit trail of all data modifications.

DynamoDB Stream and Event Table

AWS DynamoDB Streams is a powerful feature that captures a time-ordered sequence of item-level modifications in any DynamoDB table. When enabled, DynamoDB Streams records every change (insert, update, delete) made to the table in near real-time.

How It Works

Stream Capture : When data changes in the main DynamoDB table, DynamoDB Streams captures these modifications
Lambda Processing : A Lambda function is triggered by the stream and processes each change event
Event Storage : The Lambda writes these events to a separate "Events" table, creating a persistent change log
Query by Clients : The SSE endpoint can query this Events table to find changes since a specific timestamp

This approach provides several benefits:

Historical Audit Trail : All changes are permanently stored in the Events table
Efficient Polling : Clients only need to query for events after their last known event ID
Decoupling : The stream processing is separate from client synchronization logic

For more information, see the AWS DynamoDB Streams documentation.

Implementation Links

The complete implementation is available in the repository:

DynamoDB stream setup - Table configuration with streams enabled
Lambda function for stream processing - Processes DynamoDB stream events
Events table schema and setup - ElectroDB entity definition for events

Server Sent Events (SSE) Setup

Server-Sent Events (SSE) is a standard web technology that enables servers to push real-time updates to clients over a single HTTP connection. Unlike WebSockets which provide bidirectional communication, SSE is unidirectional (server to client) and uses simple HTTP, making it easier to implement and more compatible with existing infrastructure like load balancers and proxies.

Why SSE for Database Synchronization?

SSE is ideal for this use case because:

Automatic Reconnection : The browser's native EventSource API handles reconnection automatically
Simple Protocol : Uses standard HTTP, no special server infrastructure needed
Efficient : Keeps a single connection open, pushing updates only when changes occur
Last-Event-ID : Built-in support for resuming from the last received event after reconnection

SSE Endpoint Implementation

A Server-Sent Events endpoint is created using TanStack Router's createFileRoute API. This endpoint streams changes from the Events table to connected clients. Here's how the implementation works:

Key Features:

Polling Mechanism : Queries the Events table every 500ms for new changes
Heartbeat : Sends keepalive messages every 15 seconds to prevent connection timeout
Graceful Timeout : Closes the connection before Lambda timeout (14 minutes), allowing automatic reconnection
Last-Event-ID Support : Clients can reconnect and resume from their last received event
Efficient Queries : Only fetches events newer than the client's last known event

Click to view the SSE endpoint implementation

// oxlint-disable no-magic-numbers
// oxlint-disable init-declarations
// oxlint-disable no-ternary
// oxlint-disable max-statements
// oxlint-disable no-console
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
import { createFileRoute } from "@tanstack/react-router";
import { TIMEOUT_IN_SECONDS } from "../../../../lib/constructs/type";

// =============================================================================
// Constants
// =============================================================================

const STREAM_DURATION_MS = (TIMEOUT_IN_SECONDS - 4) * 1000;
const RETRY_MS = 1000;
const POLL_INTERVAL_MS = 500;
const HEARTBEAT_INTERVAL_MS = 15000; // Send heartbeat every 15 seconds to prevent connection timeout
const EVENTS_TABLE = process.env.EVENTS_TABLE ?? "";

// =============================================================================
// DynamoDB Client
// =============================================================================

const ddbClient = DynamoDBDocumentClient.from(new DynamoDBClient({}));

// =============================================================================
// Helper Functions
// =============================================================================

/** Query events from the Events table since a given sort key */
const queryEventsSince = async (
  lastEventSk: string | null,
): Promise&gt;&gt; =&gt; {
  if (!EVENTS_TABLE) {
    console.log("Persons SSE: EVENTS_TABLE not configured");
    return [];
  }

  const params = {
    TableName: EVENTS_TABLE,
    KeyConditionExpression: lastEventSk ? "pk = :pk AND sk &gt; :sk" : "pk = :pk",
    ExpressionAttributeValues: lastEventSk
      ? { ":pk": "EVENTS", ":sk": lastEventSk }
      : { ":pk": "EVENTS" },
    ScanIndexForward: true,
    Limit: 100,
  };

  console.log(
    "Persons SSE: Querying events table:",
    EVENTS_TABLE,
    "cursor:",
    lastEventSk,
  );
  const result = await ddbClient.send(new QueryCommand(params));
  console.log(
    "Persons SSE: Query returned",
    result.Items?.length ?? 0,
    "events",
  );
  return (result.Items ?? []) as Array&gt;;
};

/** Format an event as SSE data */
const formatSseEvent = (event: Record): string =&gt; {
  const data = {
    timestamp: event.createdAt,
    eventType: event.eventType,
    entityType: event.entityType,
    entity: event.entity,
    oldEntity: event.oldEntity,
  };
  return `event: change\nid: ${event.sk}\ndata: ${JSON.stringify(data)}\n\n`;
};

// =============================================================================
// SSE Stream Route for Persons DB
// =============================================================================

/**
 * SSE Stream API Route for Persons Database
 *
 * Streams entity change events (persons, addresses, bank accounts, etc.)
 * to connected clients using Server-Sent Events.
 *
 * Based on the simple /api/events blueprint pattern.
 */
export const Route = createFileRoute("/api/persons-stream")({
  server: {
    handlers: {
      GET: async ({ request }) =&gt; {
        // Check if Events table is configured
        if (!EVENTS_TABLE) {
          return new Response("SSE not configured - EVENTS_TABLE not set", {
            status: 503,
          });
        }

        // Get last event ID from header for reconnection
        const lastEventId = request.headers.get("Last-Event-ID");
        let lastSk = lastEventId;

        const encoder = new TextEncoder();
        let pollIntervalId: ReturnType;
        let heartbeatIntervalId: ReturnType;
        let timeoutId: ReturnType;

        const stream = new ReadableStream({
          async start(controller) {
            // Send retry directive so EventSource knows how long to wait before reconnecting
            controller.enqueue(encoder.encode(`retry: ${RETRY_MS}\n\n`));

            // Send initial connected event
            controller.enqueue(
              encoder.encode(
                'event: connected\ndata: {"status":"connected"}\n\n',
              ),
            );
            console.log(
              "Persons SSE: Client connected, EVENTS_TABLE:",
              EVENTS_TABLE,
            );

            // Define the poll function
            const poll = async (): Promise =&gt; {
              try {
                // Query for new events
                const events = await queryEventsSince(lastSk);

                // Send each event
                for (const event of events) {
                  controller.enqueue(encoder.encode(formatSseEvent(event)));
                  lastSk = event.sk as string;
                  console.log(
                    "Persons SSE: Sent event:",
                    event.eventType,
                    event.entityType,
                  );
                }
              } catch (error) {
                console.error("Persons SSE: Poll error:", error);
              }
            };

            // Define the heartbeat function
            const sendHeartbeat = (): void =&gt; {
              try {
                controller.enqueue(encoder.encode(": heartbeat\n\n"));
                console.log("Persons SSE: Heartbeat sent");
              } catch (error) {
                console.error("Persons SSE: Heartbeat error:", error);
              }
            };

            // Do an immediate first poll
            await poll();

            // Then poll at regular intervals
            pollIntervalId = setInterval(() =&gt; {
              poll();
            }, POLL_INTERVAL_MS);

            // Send heartbeats at regular intervals to keep connection alive
            heartbeatIntervalId = setInterval(
              sendHeartbeat,
              HEARTBEAT_INTERVAL_MS,
            );

            // Gracefully close the stream before Lambda timeout
            // EventSource will automatically reconnect
            timeoutId = setTimeout(() =&gt; {
              clearInterval(pollIntervalId);
              clearInterval(heartbeatIntervalId);
              // Send a final event to signal graceful close
              controller.enqueue(
                encoder.encode(
                  'event: reconnect\ndata: {"reason":"timeout"}\n\n',
                ),
              );
              controller.close();
              console.log(
                "Persons SSE: Stream closed gracefully before timeout",
              );
            }, STREAM_DURATION_MS);
          },
          cancel() {
            clearInterval(pollIntervalId);
            clearInterval(heartbeatIntervalId);
            clearTimeout(timeoutId);
            console.log("Persons SSE: Client disconnected");
          },
        });

        return new Response(stream, {
          headers: {
            "Content-Type": "text/event-stream",
            "Cache-Control": "no-cache",
            Connection: "keep-alive",
            "X-Accel-Buffering": "no",
          },
        });
      },
    },
  },
});

Understanding the SSE Flow

Client Connection : When a client connects, the endpoint sends a retry directive and a connected event
Initial Poll : Immediately queries for any events since the client's Last-Event-ID
Continuous Polling : Sets up an interval to poll for new events every 500ms
Event Streaming : Each new event is formatted and sent to the client with a unique ID
Heartbeat : Sends comment lines (: heartbeat) to keep the connection alive
Graceful Close : Before Lambda timeout, sends a reconnect event and closes the stream

The client's browser automatically reconnects using the built-in EventSource retry mechanism, and the server resumes streaming from the last event ID.

ElectroDB Integration (Future Enhancement)

ElectroDB, the library used for DynamoDB entity management, has community discussions about built-in change tracking. This could potentially simplify the stream processing in the future. See ElectroDB issue #74 for more details.

The SSE Hook

The client-side implementation uses a custom React hook (useSseSync) that manages the SSE connection and applies changes to TanStack DB collections. This hook abstracts away the complexity of SSE connection management and provides a clean API for components to use.

Hook Architecture

The hook is structured into several key sections:

Constants & Configuration : Defines the SSE endpoint and flag for preventing loops
Type Definitions : TypeScript interfaces for entity types, event types, and state
Collection Update Functions : Specialized functions for INSERT, MODIFY, and REMOVE operations
Change Application Logic : Routes events to the correct collection and operation
Connection Management : Handles EventSource lifecycle and reconnection

Key Features

Automatic Reconnection : Uses native EventSource which handles reconnections automatically
Loop Prevention : Uses a flag to prevent SSE updates from triggering writes back to DynamoDB
Type-Safe Updates : Strongly typed entity handlers for all five entity types (Person, Address, BankAccount, ContactInfo, Employment)
State Management : Tracks connection status and last sync time
Manual Reconnection : Provides a reconnect() function for forced reconnection

Click to view the SSE synchronization hook implementation

// oxlint-disable no-ternary
import type {
  Address,
  BankAccount,
  ContactInfo,
  Employment,
  Person,
} from "#src/webapp/types/person";
import {
  addressesCollection,
  bankAccountsCollection,
  contactsCollection,
  employmentsCollection,
  personsCollection,
} from "#src/webapp/db-collections/persons";
import { useCallback, useEffect, useRef, useState } from "react";

// =============================================================================
// Constants
// =============================================================================

const SSE_ENDPOINT = "/api/persons-stream";

// Flag to track when we're applying SSE changes
// This prevents SSE updates from triggering DynamoDB writes
let isApplyingSseChange = false;

/**
 * Check if currently applying an SSE change
 * Collection handlers can use this to skip server writes
 */
export const isFromSse = (): boolean =&gt; isApplyingSseChange;

// =============================================================================
// Types
// =============================================================================

type EntityType =
  | "person"
  | "address"
  | "bankAccount"
  | "contactInfo"
  | "employment";
type EventType = "INSERT" | "MODIFY" | "REMOVE";

interface ChangeEventData {
  timestamp?: string;
  eventType?: EventType;
  entityType?: EntityType;
  entity?: object | null;
  oldEntity?: object;
}

interface SseSyncState {
  isConnected: boolean;
  lastSyncTime: Date | null;
}

// =============================================================================
// Collection Update Functions
// =============================================================================

/**
 * Apply an INSERT change to the collection
 */
const applyInsert = (
  entityType: EntityType,
  entity: object | null | undefined,
): void =&gt; {
  if (!entity) {
    return;
  }

  // Note: TanStack DB collections handle duplicates gracefully
  // If the entity already exists, this becomes an update operation
  switch (entityType) {
    case "person":
      personsCollection.insert(entity as Person);
      break;
    case "address":
      addressesCollection.insert(entity as Address);
      break;
    case "bankAccount":
      bankAccountsCollection.insert(entity as BankAccount);
      break;
    case "contactInfo":
      contactsCollection.insert(entity as ContactInfo);
      break;
    case "employment":
      employmentsCollection.insert(entity as Employment);
      break;
  }
};

/**
 * Apply a MODIFY change to the collection
 */
const applyModify = (
  entityType: EntityType,
  entity: object | null | undefined,
): void =&gt; {
  if (!entity) {
    return;
  }

  const entityWithId = entity as { id: string };

  switch (entityType) {
    case "person":
      personsCollection.update(entityWithId.id, (draft) =&gt; {
        Object.assign(draft, entity);
      });
      break;
    case "address":
      addressesCollection.update(entityWithId.id, (draft) =&gt; {
        Object.assign(draft, entity);
      });
      break;
    case "bankAccount":
      bankAccountsCollection.update(entityWithId.id, (draft) =&gt; {
        Object.assign(draft, entity);
      });
      break;
    case "contactInfo":
      contactsCollection.update(entityWithId.id, (draft) =&gt; {
        Object.assign(draft, entity);
      });
      break;
    case "employment":
      employmentsCollection.update(entityWithId.id, (draft) =&gt; {
        Object.assign(draft, entity);
      });
      break;
  }
};

/**
 * Apply a REMOVE change to the collection
 */
const applyRemove = (
  entityType: EntityType,
  entity: object | null | undefined,
  oldEntity: object | undefined,
): void =&gt; {
  const entityWithId = entity as { id: string } | null | undefined;
  const oldEntityWithId = oldEntity as { id: string } | undefined;
  const removeId = entityWithId?.id ?? oldEntityWithId?.id;

  if (!removeId) {
    return;
  }

  switch (entityType) {
    case "person":
      personsCollection.delete(removeId);
      break;
    case "address":
      addressesCollection.delete(removeId);
      break;
    case "bankAccount":
      bankAccountsCollection.delete(removeId);
      break;
    case "contactInfo":
      contactsCollection.delete(removeId);
      break;
    case "employment":
      employmentsCollection.delete(removeId);
      break;
  }
};

/**
 * Apply a change event to the appropriate TanStack DB collection.
 * Only applies changes if they differ from current collection state.
 */
const applyChangeToCollection = (data: ChangeEventData): void =&gt; {
  if (!data.entityType || !data.eventType) {
    return;
  }

  switch (data.eventType) {
    case "INSERT":
      applyInsert(data.entityType, data.entity);
      break;
    case "MODIFY":
      applyModify(data.entityType, data.entity);
      break;
    case "REMOVE":
      applyRemove(data.entityType, data.entity, data.oldEntity);
      break;
  }
};

// =============================================================================
// Hook
// =============================================================================

/**
 * Hook for real-time SSE synchronization with TanStack DB.
 * Uses native EventSource to receive entity changes from the persons-stream endpoint.
 *
 * **IMPORTANT: Preventing Endless Loops**
 * This hook sets a global `isApplyingSseChange` flag when applying SSE changes.
 * Collection mutation handlers (onInsert/onUpdate/onDelete) should check `isFromSse()`
 * and skip DynamoDB writes when true. This breaks the loop:
 *
 * - SSE event -&gt; isApplyingSseChange=true -&gt; collection mutation -&gt; onInsert checks isFromSse()
 * -&gt; returns true -&gt; ✅ skips DynamoDB write
 * - Local user mutation -&gt; isApplyingSseChange=false -&gt; onInsert checks isFromSse()
 * -&gt; returns false -&gt; ✅ writes to DynamoDB -&gt; stream -&gt; SSE event (handled above)
 *
 * This approach allows SSE to update local state without triggering server writes,
 * while user-initiated changes still persist to DynamoDB as expected.
 *
 * EventSource automatically handles reconnection using the `retry` directive from
 * the server. The server also sends a `reconnect` event before graceful timeout
 * to signal the client that a reconnection is expected.
 *
 * Based on the simple /api/events blueprint pattern.
 *
 * @returns Object with isConnected, lastSyncTime, and reconnect function
 */
export const useSseSync = (): SseSyncState &amp; { reconnect: () =&gt; void } =&gt; {
  const eventSourceRef = useRef(null);
  const [state, setState] = useState({
    isConnected: false,
    lastSyncTime: null,
  });

  const connect = useCallback(() =&gt; {
    // Close existing connection if any
    if (eventSourceRef.current) {
      eventSourceRef.current.close();
    }

    // Create new EventSource connection
    const eventSource = new EventSource(SSE_ENDPOINT);
    eventSourceRef.current = eventSource;

    // Handle connection open
    eventSource.onopen = () =&gt; {
      setState((prev) =&gt; ({ ...prev, isConnected: true }));
    };

    // Handle connection error - EventSource will automatically reconnect
    // Based on the retry directive from the server
    eventSource.onerror = () =&gt; {
      setState((prev) =&gt; ({ ...prev, isConnected: false }));
    };

    // Handle 'connected' event from server
    eventSource.addEventListener("connected", () =&gt; {
      setState((prev) =&gt; ({ ...prev, isConnected: true }));
    });

    // Handle 'change' events (entity changes)
    eventSource.addEventListener("change", (event: MessageEvent) =&gt; {
      try {
        const data = JSON.parse(event.data) as ChangeEventData;

        // Set flag to indicate we're applying SSE changes
        // This prevents mutation handlers from writing back to DynamoDB
        isApplyingSseChange = true;
        try {
          applyChangeToCollection(data);
        } finally {
          // Always reset the flag, even if an error occurs
          isApplyingSseChange = false;
        }

        if (data.timestamp) {
          setState((prev) =&gt; ({
            ...prev,
            lastSyncTime: new Date(data.timestamp as string),
          }));
        }
      } catch {
        // Ignore parse errors
      }
    });

    // Handle 'reconnect' event (server signaling graceful close before timeout)
    // EventSource will automatically reconnect using the retry directive
    eventSource.addEventListener("reconnect", () =&gt; {
      setState((prev) =&gt; ({ ...prev, isConnected: false }));
    });
  }, []);

  const disconnect = useCallback(() =&gt; {
    if (eventSourceRef.current) {
      eventSourceRef.current.close();
      eventSourceRef.current = null;
    }
    setState((prev) =&gt; ({ ...prev, isConnected: false }));
  }, []);

  const reconnect = useCallback(() =&gt; {
    disconnect();
    connect();
  }, [connect, disconnect]);

  useEffect(() =&gt; {
    // Connect on mount
    connect();

    // Disconnect on unmount
    return () =&gt; {
      disconnect();
    };
  }, [connect, disconnect]);

  return {
    ...state,
    reconnect,
  };
};

Avoiding Infinite Loops

One of the most critical challenges when implementing real-time synchronization is preventing infinite loops. Without proper safeguards, the following cycle can occur:

SSE receives a change event from the server
Hook applies the change to the TanStack DB collection
Collection's onUpdate/onInsert/onDelete handler triggers
Handler writes the change back to DynamoDB
DynamoDB Stream captures this "new" change
Lambda writes it to the Events table
SSE endpoint streams it back to the client
Loop repeats infinitely ♾️

The Solution: Global Flag Pattern

The implementation uses a module-level flag (isApplyingSseChange) to break this cycle. Here's how it works:

When SSE Updates Occur:

SSE event received
→ Set isApplyingSseChange = true
→ Apply change to collection
→ Collection handler checks isFromSse()
→ Returns true, so SKIP DynamoDB write ✅
→ Reset isApplyingSseChange = false

When User Makes Changes:

User modifies data
→ isApplyingSseChange = false
→ Apply change to collection
→ Collection handler checks isFromSse()
→ Returns false, so WRITE to DynamoDB ✅
→ DynamoDB Stream → Events table → SSE → Other clients

Implementation in Collection Handlers

Your collection mutation handlers should implement this check:

Click to view example collection handler with loop prevention

import { isFromSse } from "./useSseSync";

personsCollection = createCollection({
  // ... other config
  onInsert: async (person) =&gt; {
    // Check if this change came from SSE
    if (isFromSse()) {
      console.log("Skipping DynamoDB write - change from SSE");
      return; // Don't write back to DynamoDB
    }

    // This is a user-initiated change, write to DynamoDB
    await writeToDynamoDB(person);
  },
  onUpdate: async (person) =&gt; {
    if (isFromSse()) return;
    await updateDynamoDB(person);
  },
  onDelete: async (id) =&gt; {
    if (isFromSse()) return;
    await deleteFromDynamoDB(id);
  },
});

This pattern ensures that:

✅ SSE updates modify local state without server writes
✅ User changes persist to DynamoDB and propagate to other clients
✅ No infinite loops or duplicate operations
✅ Clean separation between sync and user-initiated changes

Using the Hook in Components

To use the SSE synchronization in your React components, simply call the useSseSync hook:

Click to view example component usage

import { useSseSync } from "./useSseSync";

function PersonsList() {
  const { isConnected, lastSyncTime, reconnect } = useSseSync();

  return (


        {isConnected ? (
          <span>🟢 Connected</span>
        ) : (
          <span>🔴 Disconnected</span>
        )}
        {lastSyncTime &amp;&amp; (
          <span>Last sync: {lastSyncTime.toLocaleTimeString()}</span>
        )}
        Reconnect


      {/* Your persons list component */}

  );
}

The hook automatically:

Establishes the SSE connection on mount
Applies incoming changes to TanStack DB collections
Handles reconnection on errors or timeouts
Cleans up the connection on unmount

Cost Considerations

Long-Running Connections : Each SSE connection keeps a Lambda instance running for up to 14 minutes
Concurrent Connections : Each connected client requires a separate Lambda instance
Polling Overhead : The 500ms polling interval means continuous DynamoDB queries, even when no changes occur

Other Options

While SSE provides a good balance of simplicity and functionality, other approaches may be better suited for specific use cases:

1. WebSocket (Bidirectional)

When to use:

Need bidirectional communication (client can send messages to server)
High-frequency updates (many changes per second)
Lower latency requirements
Building chat or collaborative editing features

Implementation:

AWS API Gateway WebSocket API
Requires connection state management (connection IDs in DynamoDB)
More complex than SSE but more flexible

2. Short Polling

When to use:

Simple use case with infrequent updates
Need to support older browsers without SSE
Want explicit control over refresh timing

Implementation:

Standard HTTP requests on an interval (e.g., every 5-10 seconds)
Simpler than SSE but less efficient
Higher latency than push-based approaches

3. GraphQL Subscriptions

When to use:

Already using GraphQL (AWS AppSync)
Need fine-grained subscription filtering
Want managed infrastructure

Implementation:

AWS AppSync with DynamoDB resolvers
Built-in authorization and subscription management
Higher per-request cost than Lambda

4. Custom WebSocket Collection (TanStack DB)

TanStack DB supports creating custom collections with bidirectional WebSocket synchronization. This is the most integrated approach but requires the most implementation effort.

When to use:

Need full bidirectional sync (client changes immediately propagate)
Want conflict resolution at the collection level
Building offline-first applications

Resources:

TanStack DB Collection Options Guide
Requires implementing custom WebSocket server and protocol
Most complex option but provides the richest synchronization features

Conclusion

This implementation demonstrates how to build real-time data synchronization between AWS DynamoDB and TanStack DB using Server-Sent Events. The key takeaways are:

DynamoDB Streams + Events Table : Provides a reliable, queryable change log
SSE with TanStack Router : Simple, standards-based approach to server push
Loop Prevention : Critical pattern using a global flag to prevent infinite updates
Automatic Reconnection : Built-in browser support makes SSE resilient
Cost Awareness : Monitor Lambda and DynamoDB costs, especially with many concurrent connections

The SSE approach works well for:

✅ Applications with moderate update frequency (seconds to minutes)
✅ Primarily server-to-client updates
✅ Standard web browsers
✅ Simple implementation requirements

For applications requiring bidirectional real-time communication, lower latency, or offline support, consider WebSocket or TanStack DB's custom collection approach.

Source Code

The complete implementation is available on GitHub:

References

Use a customized CDK bootstrap template

Johannes Konings — Wed, 31 Dec 2025 08:15:18 +0000

Introduction

In some cases, the CDK bootstrap resources need changes beyond what's possible with the standard bootstrap parameters. While the CDK provides customization options, certain configurations require customizing of the template.

This post demonstrates how to:

Encrypt the staging bucket with a custom KMS key
Enable server access logs for the staging bucket
Validate CloudFormation templates with cdk-nag before deployment
Use the CDK Toolkit library to orchestrate the entire process in TypeScript

While the KMS key can be configured via bootstrap parameters, server access logging requires template customization. Since TypeScript is used for the CDK setup, all scripting will also be in TypeScript using the AWS CDK Toolkit library.

Additionally, we'll use cdk-nag to bridge the gap between CloudFormation templates and CDK validation rules.

Create the Resources for Bootstrap via CloudFormation

Before customizing the bootstrap template, we need to create supporting resources via CloudFormation:

A KMS key for encrypting the staging bucket
A log bucket for storing server access logs

These resources will be referenced during the bootstrap process via CloudFormation exports.

KMS Key Template

Show KMS template

AWSTemplateFormatVersion: "2010-09-09"
Description: KMS Key for encrypting the CDK bootstrap bucket
Resources:
  CdkBootstrapKmsKey:
    Type: AWS::KMS::Key
    DeletionPolicy: Retain
    UpdateReplacePolicy: Retain
    Properties:
      Description: KMS Key for CDK Bootstrap Bucket
      EnableKeyRotation: true
      KeyPolicy:
        Version: "2012-10-17"
        Statement:
          - Sid: Enable IAM User Permissions
            Effect: Allow
            Principal:
              AWS: !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:root"
            Action: "kms:*"
            Resource: "*"
          - Sid: Allow CDK roles to use the key
            Effect: Allow
            Principal:
              AWS: !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:root"
            Action:
              - "kms:Encrypt"
              - "kms:Decrypt"
              - "kms:ReEncrypt*"
              - "kms:GenerateDataKey*"
              - "kms:DescribeKey"
            Resource: "*"
            Condition:
              StringLike:
                "aws:PrincipalArn":
                  - !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-*-cfn-exec-role-*"
                  - !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-*-file-publishing-role-*"
                  - !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-*-image-publishing-role-*"
                  - !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-*-lookup-role-*"
                  - !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-*-deploy-role-*"
                "kms:ViaService":
                  - !Sub "s3.${AWS::Region}.amazonaws.com"
                  - !Sub "ecr.${AWS::Region}.amazonaws.com"
              ArnLike:
                "kms:EncryptionContext:aws:s3:arn":
                  - !Sub "arn:${AWS::Partition}:s3:::cdk-*-assets-${AWS::AccountId}-${AWS::Region}/*"
                "kms:EncryptionContext:aws:ecr:arn":
                  - !Sub "arn:${AWS::Partition}:ecr:${AWS::Region}:${AWS::AccountId}:repository/cdk-*-container-assets-*"
  CdkBootstrapKmsKeyAlias:
    Type: AWS::KMS::Alias
    Properties:
      AliasName: alias/cdk-bootstrap-key
      TargetKeyId: !Ref CdkBootstrapKmsKey
Outputs:
  CdkBootstrapKmsKeyId:
    Value: !Ref CdkBootstrapKmsKey
    Description: ID of the KMS key for CDK bootstrap
    Export:
      Name: cdk-bootstrap-kms-key-id

S3 Log Bucket Template

Show S3 log bucket template

AWSTemplateFormatVersion: "2010-09-09"
Description: "CloudFormation template for S3 log bucket with encryption and lifecycle policies"

Resources:
  LogBucket:
    Type: AWS::S3::Bucket
    Properties:
      VersioningConfiguration:
        Status: Enabled
      BucketEncryption:
        ServerSideEncryptionConfiguration:
          - ServerSideEncryptionByDefault:
              SSEAlgorithm: AES256
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true
      LifecycleConfiguration:
        Rules:
          - Id: DeleteLogsAfterRetention
            Status: Enabled
            ExpirationInDays: 90
          - Id: DeleteOldVersions
            Status: Enabled
            NoncurrentVersionExpiration:
              NoncurrentDays: 30
      Tags:
        - Key: Purpose
          Value: ApplicationLogs
        - Key: Environment
          Value: Bootstrap

  LogBucketPolicy:
    Type: AWS::S3::BucketPolicy
    Properties:
      Bucket: !Ref LogBucket
      PolicyDocument:
        Version: "2012-10-17"
        Statement:
          # AWS Best Practice: Restrict log delivery to buckets in the same account
          # See: https://docs.aws.amazon.com/AmazonS3/latest/userguide/enable-server-access-logging.html
          - Sid: AllowS3LogDeliveryWrite
            Effect: Allow
            Principal:
              Service: logging.s3.amazonaws.com
            Action: s3:PutObject
            Resource: !Sub "${LogBucket.Arn}/*"
            Condition:
              # Restrict to buckets in the same account
              StringEquals:
                aws:SourceAccount: !Ref AWS::AccountId
          - Sid: AllowS3LogDeliveryAclCheck
            Effect: Allow
            Principal:
              Service: logging.s3.amazonaws.com
            Action: s3:GetBucketAcl
            Resource: !GetAtt LogBucket.Arn
          # Note: DenyUnencryptedObjectUploads removed per AWS best practices
          # Bucket default encryption (SSE-S3) ensures all objects are encrypted
          # The S3 logging service doesn't set explicit encryption headers
          - Sid: DenyInsecureTransport
            Effect: Deny
            Principal: "*"
            Action: s3:*
            Resource:
              - !GetAtt LogBucket.Arn
              - !Sub "${LogBucket.Arn}/*"
            Condition:
              Bool:
                aws:SecureTransport: "false"

Outputs:
  LogBucketName:
    Description: Name of the log bucket
    Value: !Ref LogBucket
    Export:
      Name: log-bucket-name

The Deployment Script

A CDK app can have stacks deployed to different regions. Each region needs to be bootstrapped, so the KMS key and log bucket must be created in every region.

Using the CDK Toolkit library, we can extract the regions from the CDK app and deploy the CloudFormation templates accordingly.

The script creates CloudFormation outputs to make the resource values retrievable during bootstrap.

Show deploy script

import * as fs from "node:fs";
import * as path from "node:path";
import {
  CloudFormationClient,
  CreateStackCommand,
  type CreateStackCommandInput,
  UpdateStackCommand,
  type UpdateStackCommandInput,
  type Tag,
} from "@aws-sdk/client-cloudformation";
import { Toolkit } from "@aws-cdk/toolkit-lib";

// Parse command line arguments
const args = process.argv.slice(2);
const DRY_RUN = args.includes("--dry-run");

interface TemplateConfig {
  filename: string;
  stackName: string;
  description: string;
}

const getRegions = async (): Promise =&gt; {
  const toolkit = new Toolkit();
  const appPath = path.join(import.meta.dirname, "../../bin/app.ts");
  const cloudAssemblySource = await toolkit.fromCdkApp(`pnpx tsx ${appPath}`);

  const cloudAssembly = await toolkit.synth(cloudAssemblySource);
  const list = await toolkit.list(cloudAssembly);
  const regions = list.map((stack) =&gt; stack.environment.region);
  return regions;
};

const templates: TemplateConfig[] = [
  {
    filename: "bootstrap-kms-key.yaml",
    stackName: "cdk-bootstrap-kms-key",
    description: "KMS Key for encrypting the CDK bootstrap bucket",
  },
  {
    filename: "log-bucket.yaml",
    stackName: "cdk-bootstrap-log-bucket",
    description: "S3 log bucket with encryption and lifecycle policies",
  },
];

// Tags to apply to all stacks
const commonTags: Tag[] = [
  { Key: "Environment", Value: "bootstrap" },
  { Key: "ManagedBy", Value: "cdk-bootstrap" },
  { Key: "Purpose", Value: "cdk-deployment" },
];

async function loadTemplateContent(templatePath: string): Promise {
  try {
    const content = fs.readFileSync(templatePath, "utf-8");
    console.log(`✓ Loaded template: ${templatePath}`);
    return content;
  } catch (error) {
    console.error(`✗ Failed to load template: ${templatePath}`);
    throw error;
  }
}

async function deployOrUpdateStack(
  config: TemplateConfig,
  templateContent: string,
  region: string,
): Promise {
  const cfClient = new CloudFormationClient({ region });

  if (DRY_RUN) {
    console.log(`✓ [DRY RUN] Would deploy/update stack`);
    return "dry-run-stack-id";
  }

  // Try to update first
  try {
    const updateParams: UpdateStackCommandInput = {
      StackName: config.stackName,
      TemplateBody: templateContent,
      Tags: commonTags,
    };

    const updateCommand = new UpdateStackCommand(updateParams);
    const response = await cfClient.send(updateCommand);
    console.log(`✓ Stack updated`);
    return response.StackId!;
  } catch (error: any) {
    // If stack doesn't exist, create it
    if (error.message?.includes("does not exist")) {
      const createParams: CreateStackCommandInput = {
        StackName: config.stackName,
        TemplateBody: templateContent,
        Tags: commonTags,
        OnFailure: "DELETE",
        TimeoutInMinutes: 10,
        EnableTerminationProtection: true,
      };

      const createCommand = new CreateStackCommand(createParams);
      const response = await cfClient.send(createCommand);
      console.log(`✓ Stack created`);
      return response.StackId!;
    }

    // If no changes are detected during update, it's still successful
    if (error.message?.includes("No updates are to be performed")) {
      console.log(`✓ Stack is up to date (no changes needed)`);
      return "";
    }

    throw error;
  }
}

async function deployTemplate(
  config: TemplateConfig,
  templatePath: string,
  region: string,
): Promise {
  try {
    const templateContent = await loadTemplateContent(templatePath);

    console.log(`\n📦 Deploying stack: ${config.stackName} to ${region}`);
    const stackId = await deployOrUpdateStack(config, templateContent, region);

    if (stackId) {
      console.log(` Stack ID: ${stackId}`);
    }
  } catch (error: any) {
    console.error(`✗ Failed to deploy stack ${config.stackName}:`);
    console.error(` ${error.message}`);
    throw error;
  }
}

async function main(): Promise {
  const cfTemplatesDir = path.join(import.meta.dirname, "../cf-templates");
  const regions = await getRegions();

  console.log("🚀 Starting CloudFormation template deployment...\n");
  if (DRY_RUN) {
    console.log("⚠️ DRY RUN MODE - No actual changes will be made\n");
  }
  console.log(`Template directory: ${cfTemplatesDir}`);
  console.log(`Regions: ${regions.join(", ")}\n`);

  try {
    for (const region of regions) {
      console.log(`\n🌍 Deploying to region: ${region}`);

      for (const template of templates) {
        const templatePath = path.join(cfTemplatesDir, template.filename);
        await deployTemplate(template, templatePath, region);
      }
    }

    if (DRY_RUN) {
      console.log("\n✅ Dry run completed successfully! No changes were made.");
    } else {
      console.log("\n✅ All templates deployed successfully!");
    }
  } catch (error) {
    console.error("\n❌ Deployment failed");
    process.exit(1);
  }
}

main();

Validate CloudFormation Templates with cdk-nag

Resources within a CDK app can be validated with cdk-nag. To validate CloudFormation templates outside the CDK app, we can create a helper app that applies the same rule set to our CloudFormation templates.

As described in the cdk-nag documentation, CloudFormation templates can be included via the CfnInclude construct and validated using cdk-nag aspects.

This approach ensures:

The same validation rules are applied consistently
The same suppression mechanisms can be used
All infrastructure code follows the same security standards

Run the validation with this command:

pnpm exec tsx bootstrap/app.ts

Show cdk-nag validation script

import { CfnInclude } from "aws-cdk-lib/cloudformation-include";
import { Stack, StackProps } from "aws-cdk-lib";
import { Toolkit } from "@aws-cdk/toolkit-lib";
import { App, Aspects } from "aws-cdk-lib";
import { AwsSolutionsChecks, NagSuppressions } from "cdk-nag";

// Set region and avoid IMDS lookup for local checks
process.env.AWS_REGION = process.env.AWS_REGION || "us-east-1";
process.env.AWS_SDK_LOAD_CONFIG = "false"; // Prevent credential lookup
process.env.AWS_EC2_METADATA_SERVICE_ENDPOINT_MODE = "IPv4"; // Prevent IMDS timeout

const toolkit = new Toolkit();

const cloudAssemblySource = await toolkit.fromAssemblyBuilder(async () =&gt; {
  const app = new App();
  const stack = new Stack(app, "CdkNagCheckStack");
  new CfnInclude(stack, "BootstrapKmsKey", {
    templateFile: "./bootstrap/cf-templates/bootstrap-kms-key.yaml",
  });
  const logBucket = new CfnInclude(stack, "LogBucket", {
    templateFile: "./bootstrap/cf-templates/log-bucket.yaml",
  });
  NagSuppressions.addResourceSuppressions(
    logBucket,
    [
      {
        id: "AwsSolutions-S1",
        reason: "Log bucket does not have server access logs enabled",
      },
    ],
    true,
  );

  Aspects.of(app).add(new AwsSolutionsChecks({ verbose: true }));
  return app.synth();
});

try {
  await toolkit.synth(cloudAssemblySource);
  console.log("\n✓ Bootstrap templates synthesized successfully");
} catch (error) {
  console.error("\n✗ CDK Nag violations or synthesis errors found:");
  console.error(error);
  process.exit(1);
}

Create the Customized CDK Bootstrap Template

Get the Default Template

Customizations should be based on the standard CDK bootstrap template to ensure all necessary resources are included and the process remains compatible with future CDK versions. First, retrieve the default template using the CDK CLI.

Since the Toolkit library doesn't provide functionality to retrieve the standard template, we use the CDK CLI via a child process.

Show script to get default template

import { execSync } from "node:child_process";
import { mkdirSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { CDK_STANDDARD_TEMPLATE_FILE_NAME } from "./bootstrap";

const resultCdkStandardTemplate = execSync(
  "pnpm exec cdk bootstrap --show-template",
  {
    encoding: "utf8",
  },
);

const generatedDir = join(import.meta.dirname, "..", "generated");
mkdirSync(generatedDir, { recursive: true });

writeFileSync(
  join(generatedDir, CDK_STANDDARD_TEMPLATE_FILE_NAME),
  resultCdkStandardTemplate,
);

Customize the Template

Using a YAML parser, the standard template is loaded and modified to add the logging configuration to the staging bucket.

The log bucket configuration is embedded into the template using the CloudFormation Fn::ImportValue function, which references the log bucket created earlier. This approach is necessary because there's no way to pass the log bucket name as a parameter during the bootstrap process itself.

Show template customization script

import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { parse, stringify } from "yaml";
import {
  CDK_CUSTOMIZED_TEMPLATE_FILE_NAME,
  CDK_STANDDARD_TEMPLATE_FILE_NAME,
} from "./bootstrap";

const cdkStandardTemplate = readFileSync(
  join(
    import.meta.dirname,
    "..",
    "generated",
    CDK_STANDDARD_TEMPLATE_FILE_NAME,
  ),
  {
    encoding: "utf8",
  },
);

const cdkBootstrapTemplate = parse(cdkStandardTemplate);
if (!cdkBootstrapTemplate) {
  throw new Error("Failed to load cdk bootstrap template");
}

// Add LoggingConfiguration to StagingBucket using Fn::ImportValue
if (cdkBootstrapTemplate.Resources?.StagingBucket?.Properties) {
  cdkBootstrapTemplate.Resources.StagingBucket.Properties.LoggingConfiguration =
    {
      DestinationBucketName: { "Fn::ImportValue": "log-bucket-name" },
      LogFilePrefix: "staging-bucket-logs/",
    };
}

const generatedDir = join(import.meta.dirname, "..", "generated");
mkdirSync(generatedDir, { recursive: true });

writeFileSync(
  join(generatedDir, CDK_CUSTOMIZED_TEMPLATE_FILE_NAME),
  stringify(cdkBootstrapTemplate),
);

Bootstrap with the Customized Template

Finally, execute the CDK bootstrap process with the customized template using the Toolkit library.

Since the KMS key was created via CloudFormation, its ID must be retrieved using the CloudFormation Stack Outputs. The script:

Extracts environments (account/region pairs) from the CDK app
Retrieves the KMS key ID for each region from CloudFormation outputs
Passes the KMS key ID as a parameter to the bootstrap process

Note that the log bucket configuration is already embedded in the customized template via Fn::ImportValue, while the KMS key ID is passed as a parameter.

Show bootstrap script

import {
  BootstrapEnvironments,
  BootstrapStackParameters,
  Toolkit,
} from "@aws-cdk/toolkit-lib";
import {
  CloudFormationClient,
  DescribeStacksCommand,
} from "@aws-sdk/client-cloudformation";
import path from "node:path";
import { join } from "node:path";

export const CDK_STANDDARD_TEMPLATE_FILE_NAME =
  "resultCdkStandardTemplate.yaml";
export const CDK_CUSTOMIZED_TEMPLATE_FILE_NAME =
  "resultCdkCustomizedTemplate.yaml";

const toolkit = new Toolkit();

const templateFilePath = join(
  import.meta.dirname,
  "..",
  "generated",
  "resultCdkCustomizedTemplate.yaml",
);

const appPath = path.join(import.meta.dirname, "../../bin/app.ts");

const cloudAssemblySource = await toolkit.fromCdkApp(`pnpx tsx ${appPath}`);
// const environments: BootstrapEnvironments =
// BootstrapEnvironments.fromCloudAssemblySource(cloudAssemblySource);
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
const list = await toolkit.list(cloudAssembly);
const environmentsFromApp = list.map((stack) =&gt; {
  return {
    account: stack.environment.account,
    region: stack.environment.region,
  };
});

for (const environmentFromApp of environmentsFromApp) {
  // Get KMS Key ID from stack output
  const cfnClient = new CloudFormationClient({
    region: environmentFromApp.region,
  });
  const describeStacksResponse = await cfnClient.send(
    new DescribeStacksCommand({
      StackName: "cdk-bootstrap-kms-key",
    }),
  );

  const kmsKeyOutput = describeStacksResponse.Stacks?.[0]?.Outputs?.find(
    (output) =&gt; output.ExportName === "cdk-bootstrap-kms-key-id",
  );

  const kmsKeyId = kmsKeyOutput?.OutputValue;

  const environments: BootstrapEnvironments = BootstrapEnvironments.fromList([
    `aws://${environmentFromApp.account}/${environmentFromApp.region}`,
  ]);
  console.log(
    `Bootstrapping environment ${environmentFromApp.account}/${environmentFromApp.region} with KMS Key ID: ${kmsKeyId}`,
  );
  await toolkit.bootstrap(environments, {
    parameters: {
      parameters: {
        kmsKeyId,
      },
      keepExistingParameters: true,
    },
    source: {
      source: "custom",
      templateFile: templateFilePath,
    },
  });
}

After executing this script, the staging bucket will have:

Custom KMS encryption:

Server access logging configuration:

Conclusion

With a customized CDK bootstrap template, you can extend the bootstrap resources beyond what's possible with standard parameters. The CDK Toolkit library is an excellent tool for orchestrating the entire workflow in TypeScript, from extracting environments to deploying customized bootstrap stacks.

This approach enables:

Advanced security configurations like custom KMS encryption and access logging
Consistent validation using cdk-nag across both CDK and CloudFormation resources
Type-safe, programmatic control over the bootstrap process
Multi-region deployments with region-specific resource management

Sources and References

Simple example of TanStack DB with DynamoDB on AWS with multiple entities

Johannes Konings — Sat, 27 Dec 2025 08:15:18 +0000

Introduction

In Simple example of TanStack DB with DynamoDB on AWS, I describe how to use TanStack DB with a single entity in combination with DynamoDB.
This post contains a simple example with multiple entities and how to sync single table design with TanStack DB collections.

At a high level, we’ll go from infrastructure (a DynamoDB table), to a small DynamoDB client, to a TanStack Start server route, and finally to a TanStack DB collection that powers a simple UI.

Update: This post has been updated to include performance optimizations using global collections instead of factory-based per-person collections. This enables instant sub-millisecond navigation between person details without network requests. See the Improved data retrieval section for details.

The complete implementation is available in the tanstack-aws repository, which serves as a working example and template for this deployment pattern.

Architecture Overview

Disclaimer

This is an enhancement of a very simple example to get you started with TanStack DB and DynamoDB on AWS with multiple entities, but still simple. It is not production-ready and lacks features like error handling, security, and optimizations.

Demo Video

The following video demonstrates the improved data retrieval with global collections, showing instant navigation between person details:

The data model

This example implements a multi-entity data model for managing persons with related information. The schemas are defined using Zod as the single source of truth, with ElectroDB entities derived from these schemas to ensure type safety throughout the stack.

DynamoDB single table design

All entities are stored in a single DynamoDB table using a carefully designed key structure that enables efficient querying patterns.

Key Structure

Entity	Partition Key (pk)	Sort Key (sk)	Description
Person	`PERSON#<personId>`	`PROFILE`	Person profile data
Address	`PERSON#<personId>`	`ADDRESS#<addressId>`	Person's addresses
BankAccount	`PERSON#<personId>`	`BANK#<bankId>`	Person's bank accounts
ContactInfo	`PERSON#<personId>`	`CONTACT#<contactId>`	Person's contact info
Employment	`PERSON#<personId>`	`EMPLOYMENT#<employmentId>`	Person's employment history

This structure groups all data for a single person under the same partition key, allowing efficient retrieval of a person and all their related entities in a single query.

Access Patterns

The design supports the following access patterns:

Access Pattern	Key Condition	Description
Get all persons	GSI1: `gsi1pk = PERSONS`	List all persons
Get all addresses	GSI1: `gsi1pk = ADDRESSES`	List all addresses (for global collection)
Get all bank accounts	GSI1: `gsi1pk = BANKACCOUNTS`	List all bank accounts (for global collection)
Get all contacts	GSI1: `gsi1pk = CONTACTS`	List all contacts (for global collection)
Get all employments	GSI1: `gsi1pk = EMPLOYMENTS`	List all employments (for global collection)
Get person by ID	`pk = PERSON#<id>`, `sk = PROFILE`	Single person lookup
Get person with all data	`pk = PERSON#<id>`	Get person + all related entities (collection query)
Get person's addresses	`pk = PERSON#<id>`, `sk begins_with ADDRESS#`	All addresses for a person
Get person's bank accounts	`pk = PERSON#<id>`, `sk begins_with BANK#`	All bank accounts for a person
Get person's contacts	`pk = PERSON#<id>`, `sk begins_with CONTACT#`	All contacts for a person
Get person's employment	`pk = PERSON#<id>`, `sk begins_with EMPLOYMENT#`	All employment records for a person

The table entries will look a little bit different as ElectroDB will take care of the attribute mapping.

Global Secondary Indexes

GSI1: Multi-Entity Type Index

GSI1 is shared by ALL entity types using different partition key templates. This single GSI handles all "get all entities of type X" queries efficiently without table scans.

Entity	gsi1pk Template	gsi1sk	Query Method
Person	`PERSONS`	`lastName#firstName#id`	`PersonEntity.query.allPersons({})`
Address	`ADDRESSES`	`personId#id`	`AddressEntity.query.allAddresses({})`
BankAccount	`BANKACCOUNTS`	`personId#id`	`BankAccountEntity.query.allBankAccounts({})`
ContactInfo	`CONTACTS`	`personId#id`	`ContactInfoEntity.query.allContacts({})`
Employment	`EMPLOYMENTS`	`personId#id`	`EmploymentEntity.query.allEmployments({})`

Benefits of Single GSI1 for All Entities:

✅ No scans - Each entity type query uses an efficient Query operation
✅ Single GSI - Reduces infrastructure complexity and costs
✅ Template-based partitioning - Clean separation by entity type
✅ ElectroDB auto-populates - gsi1pk/gsi1sk populated automatically on write

This approach enables the global collections pattern for TanStack DB, where all entities are loaded once at startup and filtered client-side for instant navigation.

ElectroDB as DynamoDB client

ElectroDB simplifies working with single-table designs that contain multiple entities. In this example, a single DynamoDB table stores Person, Address, BankAccount, ContactInfo, and Employment entities using composite keys. ElectroDB handles the complexity of query building, attribute mapping, and relationship management across these entities, eliminating the need to manually construct DynamoDB expressions. It provides type-safe entity definitions (derived from Zod schemas), automatic key generation, and collection queries that efficiently retrieve related entities together—making single-table designs more maintainable and less error-prone than raw DynamoDB client code.

The schema looks like this:

Click to expand ElectroDB schema

import { getDdbDocClient } from "#src/webapp/integrations/ddb-client/ddbClient.ts";
import { zodToElectroDBAttributes } from "#src/webapp/integrations/electrodb/zod-to-electrodb.ts";
import {
  AddressSchema,
  BankAccountSchema,
  ContactInfoSchema,
  EmploymentSchema,
  PersonSchema,
} from "#src/webapp/types/person.ts";
import { Entity, type EntityConfiguration, Service } from "electrodb";

// =============================================================================
// Table Configuration
// =============================================================================

const TABLE_NAME =
  process.env.DDB_PERSONS_TABLE_NAME ?? "TanstackAwsStack-db-persons";

const getEntityConfig = (): EntityConfiguration =&gt; ({
  client: getDdbDocClient(),
  table: TABLE_NAME,
});

// =============================================================================
// Derived ElectroDB Attributes from Zod Schemas (Single Source of Truth)
// =============================================================================

const personAttributes = zodToElectroDBAttributes(PersonSchema);
const addressAttributes = zodToElectroDBAttributes(AddressSchema);
const bankAccountAttributes = zodToElectroDBAttributes(BankAccountSchema);
const contactInfoAttributes = zodToElectroDBAttributes(ContactInfoSchema);
const employmentAttributes = zodToElectroDBAttributes(EmploymentSchema);

// =============================================================================
// Person Entity
// =============================================================================

export const PersonEntity = new Entity(
  {
    model: {
      entity: "Person",
      version: "1",
      service: "persons",
    },
    attributes: personAttributes,
    indexes: {
      primary: {
        pk: { field: "pk", composite: ["id"] },
        sk: { field: "sk", composite: [] },
      },
      // GSI1: List all persons
      allPersons: {
        index: "GSI1",
        pk: { field: "gsi1pk", composite: [], template: "PERSONS" },
        sk: { field: "gsi1sk", composite: ["lastName", "firstName", "id"] },
      },
    },
  },
  getEntityConfig(),
);

// =============================================================================
// Address Entity
// =============================================================================

export const AddressEntity = new Entity(
  {
    model: {
      entity: "Address",
      version: "1",
      service: "persons",
    },
    attributes: addressAttributes,
    indexes: {
      primary: {
        pk: { field: "pk", composite: ["personId"] },
        sk: { field: "sk", composite: ["id"] },
      },
      // GSI1: Query all addresses
      allAddresses: {
        index: "GSI1",
        pk: { field: "gsi1pk", composite: [], template: "ADDRESSES" },
        sk: { field: "gsi1sk", composite: ["personId", "id"] },
      },
    },
  },
  getEntityConfig(),
);

// =============================================================================
// BankAccount Entity
// =============================================================================

export const BankAccountEntity = new Entity(
  {
    model: {
      entity: "BankAccount",
      version: "1",
      service: "persons",
    },
    attributes: bankAccountAttributes,
    indexes: {
      primary: {
        pk: { field: "pk", composite: ["personId"] },
        sk: { field: "sk", composite: ["id"] },
      },
      // GSI1: Query all bank accounts
      allBankAccounts: {
        index: "GSI1",
        pk: { field: "gsi1pk", composite: [], template: "BANKACCOUNTS" },
        sk: { field: "gsi1sk", composite: ["personId", "id"] },
      },
    },
  },
  getEntityConfig(),
);

// =============================================================================
// ContactInfo Entity
// =============================================================================

export const ContactInfoEntity = new Entity(
  {
    model: {
      entity: "ContactInfo",
      version: "1",
      service: "persons",
    },
    attributes: contactInfoAttributes,
    indexes: {
      primary: {
        pk: { field: "pk", composite: ["personId"] },
        sk: { field: "sk", composite: ["id"] },
      },
      // GSI1: Query all contacts
      allContacts: {
        index: "GSI1",
        pk: { field: "gsi1pk", composite: [], template: "CONTACTS" },
        sk: { field: "gsi1sk", composite: ["personId", "id"] },
      },
    },
  },
  getEntityConfig(),
);

// =============================================================================
// Employment Entity
// =============================================================================

export const EmploymentEntity = new Entity(
  {
    model: {
      entity: "Employment",
      version: "1",
      service: "persons",
    },
    attributes: employmentAttributes,
    indexes: {
      primary: {
        pk: { field: "pk", composite: ["personId"] },
        sk: { field: "sk", composite: ["id"] },
      },
      // GSI1: Query all employments
      allEmployments: {
        index: "GSI1",
        pk: { field: "gsi1pk", composite: [], template: "EMPLOYMENTS" },
        sk: { field: "gsi1sk", composite: ["personId", "id"] },
      },
    },
  },
  getEntityConfig(),
);

// =============================================================================
// Persons Service - Collection Queries
// =============================================================================

new Service(
  {
    person: PersonEntity,
    address: AddressEntity,
    bankAccount: BankAccountEntity,
    contactInfo: ContactInfoEntity,
    employment: EmploymentEntity,
  },
  getEntityConfig(),
);

Certain fields are derived from Zod schemas to ensure type safety throughout the stack and have a single source of truth

Full implementation: person.ts (Zod Schemas) | entities.ts (ElectroDB Entities) | zod-to-electrodb.ts

The persons client

This wrapper around ElectroDB entities provides type-safe methods for performing CRUD operations on persons and their related entities. The updated version includes getAllX methods for each entity type that query GSI1 to support global collections.

Full implementation: personsClient.ts

Click to expand personsClient.ts

/**
 * ElectroDB-based Persons Client
 *
 * Uses ElectroDB entities for type-safe DynamoDB operations.
 */

import type {
  Address,
  BankAccount,
  ContactInfo,
  Employment,
  Person,
} from "#src/webapp/types/person.ts";
import {
  AddressEntity,
  BankAccountEntity,
  ContactInfoEntity,
  EmploymentEntity,
  PersonEntity,
} from "#src/webapp/integrations/electrodb/entities.ts";

// =============================================================================
// Person Operations
// =============================================================================

/**
 * Get all persons using GSI1
 */
export const getAllPersons = async (): Promise =&gt; {
  const result = await PersonEntity.query.allPersons({}).go();
  return result.data.map((item) =&gt; ({
    id: item.id,
    firstName: item.firstName,
    lastName: item.lastName,
    dateOfBirth: item.dateOfBirth,
    gender: item.gender,
    createdAt: item.createdAt,
    updatedAt: item.updatedAt,
  }));
};

/**
 * Create a new person
 */
export const createPerson = async (person: Person): Promise =&gt; {
  const result = await PersonEntity.put(person).go();
  return result.data as Person;
};

/**
 * Update a person
 * Uses put with merged data to ensure GSI1 composite keys are properly formatted
 */
export const updatePerson = async (
  personId: string,
  updates: Partial,
): Promise =&gt; {
  // First, get the current person to merge with updates
  const current = await PersonEntity.get({ id: personId }).go();
  if (!current.data) {
    throw new Error(`Person with id ${personId} not found`);
  }

  // Merge current data with updates and use put to replace the item
  const updatedPerson = {
    id: personId,
    firstName: updates.firstName ?? current.data.firstName,
    lastName: updates.lastName ?? current.data.lastName,
    dateOfBirth: updates.dateOfBirth ?? current.data.dateOfBirth,
    gender: updates.gender ?? current.data.gender,
    createdAt: current.data.createdAt,
    updatedAt: updates.updatedAt ?? new Date().toISOString(),
  };

  const result = await PersonEntity.put(updatedPerson).go();
  return result.data as Person;
};

/**
 * Delete a person and all related entities
 */
export const deletePerson = async (personId: string): Promise =&gt; {
  // Delete all related entities first
  const [addresses, bankAccounts, contacts, employments] = await Promise.all([
    AddressEntity.query.primary({ personId }).go(),
    BankAccountEntity.query.primary({ personId }).go(),
    ContactInfoEntity.query.primary({ personId }).go(),
    EmploymentEntity.query.primary({ personId }).go(),
  ]);

  // Delete all related items
  await Promise.all([
    ...addresses.data.map((addr) =&gt;
      AddressEntity.delete({ personId, id: addr.id }).go(),
    ),
    ...bankAccounts.data.map((bank) =&gt;
      BankAccountEntity.delete({ personId, id: bank.id }).go(),
    ),
    ...contacts.data.map((contact) =&gt;
      ContactInfoEntity.delete({ personId, id: contact.id }).go(),
    ),
    ...employments.data.map((emp) =&gt;
      EmploymentEntity.delete({ personId, id: emp.id }).go(),
    ),
    PersonEntity.delete({ id: personId }).go(),
  ]);
};

// =============================================================================
// Address Operations
// =============================================================================

/**
 * Get all addresses using GSI1 (allAddresses)
 * Uses partition key template 'ADDRESSES' for efficient querying
 */
export const getAllAddresses = async (): Promise =&gt; {
  const result = await AddressEntity.query.allAddresses({}).go();
  return result.data as Address[];
};

export const createAddress = async (address: Address): Promise =&gt; {
  const result = await AddressEntity.put(address).go();
  return result.data as Address;
};

export const updateAddress = async (address: Address): Promise =&gt; {
  const result = await AddressEntity.put(address).go();
  return result.data as Address;
};

export const deleteAddress = async (
  personId: string,
  addressId: string,
): Promise =&gt; {
  await AddressEntity.delete({ personId, id: addressId }).go();
};

// =============================================================================
// BankAccount Operations
// =============================================================================

/**
 * Get all bank accounts using GSI1 (allBankAccounts)
 */
export const getAllBankAccounts = async (): Promise =&gt; {
  const result = await BankAccountEntity.query.allBankAccounts({}).go();
  return result.data as BankAccount[];
};

export const createBankAccount = async (
  bankAccount: BankAccount,
): Promise =&gt; {
  const result = await BankAccountEntity.put(bankAccount).go();
  return result.data as BankAccount;
};

export const updateBankAccount = async (
  bankAccount: BankAccount,
): Promise =&gt; {
  const result = await BankAccountEntity.put(bankAccount).go();
  return result.data as BankAccount;
};

export const deleteBankAccount = async (
  personId: string,
  bankAccountId: string,
): Promise =&gt; {
  await BankAccountEntity.delete({ personId, id: bankAccountId }).go();
};

// =============================================================================
// ContactInfo Operations
// =============================================================================

/**
 * Get all contacts using GSI1 (allContacts)
 */
export const getAllContacts = async (): Promise =&gt; {
  const result = await ContactInfoEntity.query.allContacts({}).go();
  return result.data as ContactInfo[];
};

export const createContact = async (
  contact: ContactInfo,
): Promise =&gt; {
  const result = await ContactInfoEntity.put(contact).go();
  return result.data as ContactInfo;
};

export const updateContact = async (
  contact: ContactInfo,
): Promise =&gt; {
  const result = await ContactInfoEntity.put(contact).go();
  return result.data as ContactInfo;
};

export const deleteContact = async (
  personId: string,
  contactId: string,
): Promise =&gt; {
  await ContactInfoEntity.delete({ personId, id: contactId }).go();
};

// =============================================================================
// Employment Operations
// =============================================================================

// Helper to convert null to undefined for ElectroDB compatibility
const normalizeEmployment = (employment: Employment) =&gt; ({
  ...employment,
  endDate: employment.endDate ?? undefined,
});

/**
 * Get all employments using GSI1 (allEmployments)
 */
export const getAllEmployments = async (): Promise =&gt; {
  const result = await EmploymentEntity.query.allEmployments({}).go();
  return result.data as Employment[];
};

export const createEmployment = async (
  employment: Employment,
): Promise =&gt; {
  const result = await EmploymentEntity.put(
    normalizeEmployment(employment),
  ).go();
  return result.data as Employment;
};

export const updateEmployment = async (
  employment: Employment,
): Promise =&gt; {
  const result = await EmploymentEntity.put(
    normalizeEmployment(employment),
  ).go();
  return result.data as Employment;
};

export const deleteEmployment = async (
  personId: string,
  employmentId: string,
): Promise =&gt; {
  await EmploymentEntity.delete({ personId, id: employmentId }).go();
};

The new GSI for DynamoDB

The DynamoDB table uses a single GSI that serves all entity types with different partition key templates. This enables efficient querying of all entities of a specific type without table scans.

Full implementation: DatabasePersons.ts

Click to expand DatabasePersons.ts

import {
  AttributeType,
  BillingMode,
  ProjectionType,
  Table,
} from "aws-cdk-lib/aws-dynamodb";
import { Construct } from "constructs";

export class DatabasePersons extends Construct {
  public readonly dbPersons: Table;
  constructor(scope: Construct, id: string) {
    super(scope, id);

    this.dbPersons = new Table(this, "Persons", {
      partitionKey: { name: "pk", type: AttributeType.STRING },
      sortKey: { name: "sk", type: AttributeType.STRING },
      billingMode: BillingMode.PAY_PER_REQUEST,
    });

    // GSI1: Multi-entity type index
    // Serves all entity types with different gsi1pk templates:
    // - PERSONS, ADDRESSES, BANKACCOUNTS, CONTACTS, EMPLOYMENTS
    this.dbPersons.addGlobalSecondaryIndex({
      indexName: "GSI1",
      partitionKey: { name: "gsi1pk", type: AttributeType.STRING },
      sortKey: { name: "gsi1sk", type: AttributeType.STRING },
      projectionType: ProjectionType.ALL,
    });
  }
}

The TanStack DB collection with server functions

The updated implementation uses global collections instead of factory-based per-person collections. This approach loads all entities once at app startup and enables instant sub-millisecond navigation between person details without network requests.

Full implementation: persons.ts (collections)

Click to expand persons.ts (TanStack DB global collections)

import * as electrodbClient from "#src/webapp/integrations/electrodb/personsClient";
import { getContext } from "#src/webapp/integrations/tanstack-query/root-provider";
import {
  type Address,
  AddressSchema,
  type BankAccount,
  BankAccountSchema,
  type ContactInfo,
  ContactInfoSchema,
  type Employment,
  EmploymentSchema,
  type Person,
  PersonSchema,
} from "#src/webapp/types/person";
import { queryCollectionOptions } from "@tanstack/query-db-collection";
import { createCollection } from "@tanstack/react-db";
import { createServerFn } from "@tanstack/react-start";

// =============================================================================
// Server Functions - Global Fetchers
// =============================================================================

/**
 * Get all persons (profile only)
 */
const fetchPersons = createServerFn({ method: "GET" }).handler(async () =&gt;
  electrodbClient.getAllPersons(),
);

/**
 * Get all addresses (global)
 */
const fetchAllAddresses = createServerFn({ method: "GET" }).handler(async () =&gt;
  electrodbClient.getAllAddresses(),
);

/**
 * Get all bank accounts (global)
 */
const fetchAllBankAccounts = createServerFn({ method: "GET" }).handler(
  async () =&gt; electrodbClient.getAllBankAccounts(),
);

/**
 * Get all contacts (global)
 */
const fetchAllContacts = createServerFn({ method: "GET" }).handler(async () =&gt;
  electrodbClient.getAllContacts(),
);

/**
 * Get all employments (global)
 */
const fetchAllEmployments = createServerFn({ method: "GET" }).handler(
  async () =&gt; electrodbClient.getAllEmployments(),
);

// ... mutation server functions (createPersonFn, updatePersonFn, etc.)

// =============================================================================
// TanStack DB Global Collections
// =============================================================================

/**
 * Persons Collection - Main collection for person profiles
 *
 * Uses eager sync mode (default) - all persons loaded upfront.
 * Good for datasets &lt; 10k rows.
 */
export const personsCollection = createCollection(
  queryCollectionOptions({
    queryKey: ["persons"],
    queryFn: () =&gt; fetchPersons(),
    queryClient: getContext().queryClient,
    getKey: (item) =&gt; item.id,
    onInsert: async ({ transaction }) =&gt; {
      await Promise.all(
        transaction.mutations.map((mutation) =&gt;
          createPersonFn({ data: mutation.modified as Person }),
        ),
      );
    },
    onUpdate: async ({ transaction }) =&gt; {
      await Promise.all(
        transaction.mutations.map((mutation) =&gt;
          updatePersonFn({
            data: {
              personId: mutation.key as string,
              updates: mutation.changes as Partial,
            },
          }),
        ),
      );
    },
    onDelete: async ({ transaction }) =&gt; {
      await Promise.all(
        transaction.mutations.map((mutation) =&gt;
          deletePersonFn({ data: mutation.key as string }),
        ),
      );
    },
  }),
);

/**
 * Global Addresses Collection
 *
 * All addresses loaded once, joined client-side with persons.
 * Enables instant navigation between person details without network calls.
 */
export const addressesCollection = createCollection(
  queryCollectionOptions({
    queryKey: ["addresses"],
    queryFn: () =&gt; fetchAllAddresses(),
    queryClient: getContext().queryClient,
    getKey: (item) =&gt; item.id,
    // ... onInsert, onUpdate, onDelete handlers
  }),
);

/**
 * Global Bank Accounts Collection
 */
export const bankAccountsCollection = createCollection(
  queryCollectionOptions({
    queryKey: ["bankAccounts"],
    queryFn: () =&gt; fetchAllBankAccounts(),
    queryClient: getContext().queryClient,
    getKey: (item) =&gt; item.id,
    // ... onInsert, onUpdate, onDelete handlers
  }),
);

/**
 * Global Contacts Collection
 */
export const contactsCollection = createCollection(
  queryCollectionOptions({
    queryKey: ["contacts"],
    queryFn: () =&gt; fetchAllContacts(),
    queryClient: getContext().queryClient,
    getKey: (item) =&gt; item.id,
    // ... onInsert, onUpdate, onDelete handlers
  }),
);

/**
 * Global Employments Collection
 */
export const employmentsCollection = createCollection(
  queryCollectionOptions({
    queryKey: ["employments"],
    queryFn: () =&gt; fetchAllEmployments(),
    queryClient: getContext().queryClient,
    getKey: (item) =&gt; item.id,
    // ... onInsert, onUpdate, onDelete handlers
  }),
);

The key difference from the previous factory-based approach is that all collections are now global singletons that load all entities once at app startup. The client-side filtering using TanStack DB's eq() operator provides instant navigation between persons.

The hook

Custom React hooks provide a clean interface for components to interact with the TanStack DB collections. The updated usePersons hook now also prefetches all entity data for instant person detail loading. The usePersonDetail hook uses TanStack DB's eq() operator to filter the global collections client-side, providing sub-millisecond navigation.

Full implementation: useDbPersons.ts

Click to expand useDbPersons.ts

import type {
  Address,
  BankAccount,
  ContactInfo,
  Employment,
  Person,
} from "#src/webapp/types/person";
import {
  addressesCollection,
  bankAccountsCollection,
  contactsCollection,
  employmentsCollection,
  personsCollection,
} from "#src/webapp/db-collections/persons";
import { eq, useLiveQuery } from "@tanstack/react-db";

// =============================================================================
// Prefetch Person Entities Hook
// =============================================================================

/**
 * Hook to prefetch all person-related entity collections.
 * Call this after persons are loaded to ensure entity data is available
 * immediately when a user selects a person.
 */
export function usePrefetchPersonEntities() {
  const addressesQuery = useLiveQuery(addressesCollection);
  const bankAccountsQuery = useLiveQuery(bankAccountsCollection);
  const contactsQuery = useLiveQuery(contactsCollection);
  const employmentsQuery = useLiveQuery(employmentsCollection);

  return {
    isLoading:
      addressesQuery.isLoading ||
      bankAccountsQuery.isLoading ||
      contactsQuery.isLoading ||
      employmentsQuery.isLoading,
    isReady:
      !addressesQuery.isLoading &amp;&amp;
      !bankAccountsQuery.isLoading &amp;&amp;
      !contactsQuery.isLoading &amp;&amp;
      !employmentsQuery.isLoading,
  };
}

// =============================================================================
// Persons List Hook
// =============================================================================

/**
 * Hook for accessing and mutating the persons collection.
 * Also prefetches entity data for instant person detail loading.
 */
export function usePersons() {
  const query = useLiveQuery(personsCollection);

  // Prefetch entity data once persons start loading
  const entitiesPrefetch = usePrefetchPersonEntities();

  const addPerson = (person: Person) =&gt; {
    personsCollection.insert(person);
  };

  const updatePerson = (id: string, changes: Partial) =&gt; {
    personsCollection.update(id, (draft) =&gt; {
      Object.assign(draft, changes, { updatedAt: new Date().toISOString() });
    });
  };

  const deletePerson = (id: string) =&gt; {
    personsCollection.delete(id);
  };

  return {
    persons: query.data ?? [],
    isLoading: query.isLoading,
    isError: query.isError,
    isEntitiesReady: entitiesPrefetch.isReady,
    addPerson,
    updatePerson,
    deletePerson,
  };
}

// =============================================================================
// Combined Person Detail Hook (Using TanStack DB Joins)
// =============================================================================

/**
 * Hook for accessing a person with all related entities using global collections.
 *
 * Benefits over factory-based collections:
 * - All data loaded once at app startup
 * - Navigation between persons is instant (sub-millisecond)
 * - No network requests when switching between person details
 * - Differential dataflow updates only what changed
 */
export function usePersonDetail(personId: string) {
  // Query person by ID using eq() from global collection
  const personQuery = useLiveQuery(
    (query) =&gt;
      query
        .from({ persons: personsCollection })
        .where(({ persons }) =&gt; eq(persons.id, personId)),
    [personId],
  );

  // Query addresses for this person from global collection
  const addressesQuery = useLiveQuery(
    (query) =&gt;
      query
        .from({ addresses: addressesCollection })
        .where(({ addresses }) =&gt; eq(addresses.personId, personId)),
    [personId],
  );

  // Query bank accounts for this person from global collection
  const bankAccountsQuery = useLiveQuery(
    (query) =&gt;
      query
        .from({ bankAccounts: bankAccountsCollection })
        .where(({ bankAccounts }) =&gt; eq(bankAccounts.personId, personId)),
    [personId],
  );

  // Query contacts for this person from global collection
  const contactsQuery = useLiveQuery(
    (query) =&gt;
      query
        .from({ contacts: contactsCollection })
        .where(({ contacts }) =&gt; eq(contacts.personId, personId)),
    [personId],
  );

  // Query employments for this person from global collection
  const employmentsQuery = useLiveQuery(
    (query) =&gt;
      query
        .from({ employments: employmentsCollection })
        .where(({ employments }) =&gt; eq(employments.personId, personId)),
    [personId],
  );

  const isLoading =
    personQuery.isLoading ||
    addressesQuery.isLoading ||
    bankAccountsQuery.isLoading ||
    contactsQuery.isLoading ||
    employmentsQuery.isLoading;

  // Person mutations
  const updatePerson = (changes: Partial) =&gt; {
    personsCollection.update(personId, (draft) =&gt; {
      Object.assign(draft, changes, { updatedAt: new Date().toISOString() });
    });
  };

  const deletePerson = () =&gt; {
    personsCollection.delete(personId);
  };

  // ... mutation functions for addresses, bank accounts, contacts, employments

  return {
    person: personQuery.data?.[0],
    addresses: addressesQuery.data ?? [],
    bankAccounts: bankAccountsQuery.data ?? [],
    contacts: contactsQuery.data ?? [],
    employments: employmentsQuery.data ?? [],
    isLoading,
    updatePerson,
    deletePerson,
    // ... other mutation functions
  };
}

Improved data retrieval: Global collections

The key improvement in this update is the shift from factory-based per-person collections to global collections. This architectural change provides significant performance benefits:

Previous approach (Factory Collections)

// Created new collection for each personId - multiple network requests
const createAddressesCollection = (personId: string) =>
  createCollection({
    queryKey: ["persons", personId, "addresses"],
    queryFn: () => fetchAddresses(personId), // Network request per person
  });

New approach (Global Collections)

// Single global collection - one network request, client-side filtering
export const addressesCollection = createCollection({
  queryKey: ["addresses"],
  queryFn: () => fetchAllAddresses(), // Uses GSI1: gsi1pk = 'ADDRESSES'
});

Performance comparison

Metric	Factory Collections	Global Collections
Network requests per navigation	4-5 (one per entity)	0 (data already loaded)
Time to show person details	100-500ms	<1ms
Memory efficiency	Duplicate per person	Normalized, shared data
Cache reuse	None	Full TanStack Query cache

When to use which approach

Data Size	Recommended Mode	Reason
< 10k rows	Eager (global)	Load everything upfront, instant queries
10k-50k rows	Progressive	Fast first paint, background sync
> 50k rows	On-demand	Query-driven loading with predicate push

Our persons example uses Eager mode since typical datasets are well under 10k entities.

Seed the database

A seed script populates the DynamoDB table with realistic test data using Faker. It creates persons with all related entities, handles batching to avoid throttling, and supports clearing existing data before seeding.

Full implementation: seed-persons.ts

Click to expand seed-persons.ts

#!/usr/bin/env node
// oxlint-disable max-statements
/* oxlint-disable no-console, no-await-in-loop, no-magic-numbers */
/**
 * Seed Script for DB Persons
 *
 * Populates the DynamoDB Persons table with fake data.
 * Uses ElectroDB client and faker data generators.
 *
 * Usage:
 *   pnpm seed:persons
 *   pnpm seed:persons 100     # Seed 100 persons
 *   pnpm seed:persons --clear # Clear existing data first
 */

import type {
  ContactInfo,
  Employment,
  PersonWithRelations,
} from "#src/webapp/types/person.ts";
import { generatePersons, initFaker } from "#src/webapp/data/fake-persons.ts";
import {
  createAddress,
  createBankAccount,
  createContact,
  createEmployment,
  createPerson,
  deletePerson,
  getAllPersons,
} from "#src/webapp/integrations/electrodb/personsClient.ts";

// =============================================================================
// Configuration
// =============================================================================

const DEFAULT_COUNT = 50;
const BATCH_SIZE = 10;
const LOG_INTERVAL = 10;

// =============================================================================
// Helpers
// =============================================================================

const normalizeContactInfo = (
  contact: ContactInfo,
): Omit &amp; { isVerified: boolean } =&gt; ({
  ...contact,
  isVerified: contact.isVerified ?? false,
});

const normalizeEmployment = (
  employment: Employment,
): Omit &amp; { endDate: string | undefined } =&gt; ({
  ...employment,
  endDate: employment.endDate ?? undefined,
});

const sleep = (ms: number) =&gt; new Promise((resolve) =&gt; setTimeout(resolve, ms));

// =============================================================================
// Seed Functions
// =============================================================================

const seedOnePerson = async (
  personData: PersonWithRelations,
): Promise =&gt; {
  // Create the person
  await createPerson({
    id: personData.id,
    firstName: personData.firstName,
    lastName: personData.lastName,
    dateOfBirth: personData.dateOfBirth,
    gender: personData.gender,
    createdAt: personData.createdAt,
    updatedAt: personData.updatedAt,
  });

  // Create related entities in parallel
  await Promise.all([
    ...personData.addresses.map((addr) =&gt; createAddress(addr)),
    ...personData.bankAccounts.map((bank) =&gt; createBankAccount(bank)),
    ...personData.contacts.map((contact) =&gt;
      createContact(normalizeContactInfo(contact)),
    ),
    ...personData.employments.map((emp) =&gt;
      createEmployment(normalizeEmployment(emp)),
    ),
  ]);
};

const seedPersonsBatch = async (
  persons: PersonWithRelations[],
): Promise =&gt; {
  let successCount = 0;

  for (const person of persons) {
    try {
      await seedOnePerson(person);
      successCount++;
    } catch (error) {
      console.error(`Failed to seed person ${person.id}:`, error);
    }
  }

  return successCount;
};

const clearAllPersons = async (): Promise =&gt; {
  console.log("Clearing existing persons...");

  const existingPersons = await getAllPersons();
  let deletedCount = 0;

  for (const person of existingPersons) {
    try {
      await deletePerson(person.id);
      deletedCount++;
      if (deletedCount % LOG_INTERVAL === 0) {
        console.log(
          `  Deleted ${deletedCount}/${existingPersons.length} persons...`,
        );
      }
    } catch (error) {
      console.error(`Failed to delete person ${person.id}:`, error);
    }
  }

  console.log(`Cleared ${deletedCount} persons`);
  return deletedCount;
};

// =============================================================================
// Main
// =============================================================================

const main = async () =&gt; {
  // Parse arguments
  const args = process.argv.slice(2);
  const shouldClear = args.includes("--clear");
  const countArg = args.find((arg) =&gt; !arg.startsWith("--"));
  let count = DEFAULT_COUNT;
  if (countArg) {
    count = parseInt(countArg, 10);
  }

  console.log("=".repeat(60));
  console.log("DB Persons Seed Script");
  console.log("=".repeat(60));

  // Check for table name
  const tableName = process.env.DDB_PERSONS_TABLE_NAME;
  if (!tableName) {
    console.error("Error: DDB_PERSONS_TABLE_NAME environment variable not set");
    console.log("\nRun: export DDB_PERSONS_TABLE_NAME=");
    process.exit(1);
  }
  console.log(`Table: ${tableName}`);

  // Clear if requested
  if (shouldClear) {
    await clearAllPersons();
    console.log("");
  }

  // Generate fake data
  console.log(`Generating ${count} persons...`);
  initFaker();
  const persons = generatePersons(count);
  console.log(`Generated ${persons.length} persons with relations`);

  // Seed in batches
  console.log(`\nSeeding in batches of ${BATCH_SIZE}...`);
  let totalSeeded = 0;

  for (let idx = 0; idx &lt; persons.length; idx += BATCH_SIZE) {
    const batch = persons.slice(idx, idx + BATCH_SIZE);
    const seeded = await seedPersonsBatch(batch);
    totalSeeded += seeded;

    console.log(`  Seeded ${totalSeeded}/${persons.length} persons...`);

    // Small delay to avoid throttling
    await sleep(100);
  }

  console.log("");
  console.log("=".repeat(60));
  console.log(`Seed Complete: ${totalSeeded} persons created`);
  console.log("=".repeat(60));
};

main().catch((error) =&gt; {
  console.error("Seed script failed:", error);
  process.exit(1);
});

Result

The implementation demonstrates a multi-entity data model with DynamoDB's single table design. The DynamoDB table shows the hierarchical key structure with person profiles and related entities stored efficiently. The UI displays the person list with all associated data managed through TanStack DB collections.

Conclusion

Because ElectroDB handles the entities and single table design, it's more or less a direct mapping from the ElectroDB client to TanStack DB collections.
At least for the described data model and access patterns.

The update to global collections demonstrates how TanStack DB's architecture enables significant performance improvements with minimal code changes. By loading all entities once at startup and filtering client-side, navigation between person details becomes instant—no network requests needed.

At this size of around 10-50 persons, this approach works well. With much more data (>10k rows), you may need to consider progressive or on-demand loading strategies. TanStack DB's query-driven sync patterns support these scenarios as your data grows.

Sources and References

Examples (full implementation on GitHub): github.com/JohannesKonings/tanstack-aws
Original tag: 2025-12-27-tanstack-start-aws-db-multiple-entities
Updated tag (global collections): 2025-12-27-tanstack-start-aws-db-multiple-entities-update
TanStack DB documentation: tanstack.com/db/latest
TanStack DB 0.5 Query-Driven Sync: tanstack.com/blog/tanstack-db-0.5-query-driven-sync
ElectroDB documentation: electrodb.dev

Simple example of TanStack DB with DynamoDB on AWS

Johannes Konings — Sat, 20 Dec 2025 08:15:18 +0000

Introduction

In Deploying TanStack Start on AWS with Lambda Function URLs, I describe how to deploy TanStack Start serverless on AWS. This post contains a simple example of using TanStack DB (https://tanstack.com/db/latest) with DynamoDB on AWS.

At a high level, we’ll go from infrastructure (a DynamoDB table), to a small DynamoDB client, to a TanStack Start server route, and finally to a TanStack DB collection that powers a simple UI.

The complete implementation is available in the tanstack-aws repository, which serves as a working example and template for this deployment pattern.

Disclaimer

This is a very simple example to get you started with TanStack DB and DynamoDB on AWS. It is not production-ready and lacks features like error handling, security, and optimizations.

TanStack DB

This (https://frontendatscale.com/blog/tanstack-db/) blog post explains the concepts of TanStack DB very well. In short, TanStack DB is a client-first database that runs in the browser or in a server environment. It provides a simple API to store, query, and sync data. TanStack DB is based on collections, with existing sync engines like ElectricSQL (https://tanstack.com/db/latest/docs/collections/electric-collection).

This post uses the Query Collection to wire it via an API to DynamoDB (https://tanstack.com/db/latest/docs/collections/query-collection).

The idea is straightforward: TanStack DB remains the place where your app reads and writes “records” (in this case, todos), while the collection’s fetch and mutation hooks delegate persistence to your own backend API.

DynamoDB in CDK

This is a very simple configuration, just to store the todos.

To keep the example focused, the table uses a generic partition key and sort key (pk/sk). That makes it easy to evolve into a single-table design later, while keeping the code here minimal.

import { AttributeType, BillingMode, Table } from "aws-cdk-lib/aws-dynamodb";
import { Construct } from "constructs";

export class DatabaseTodos extends Construct {
  public readonly dbTodos: Table;
  constructor(scope: Construct, id: string) {
    super(scope, id);

    this.dbTodos = new Table(this, "Todos", {
      partitionKey: { name: "pk", type: AttributeType.STRING },
      sortKey: { name: "sk", type: AttributeType.STRING },
      billingMode: BillingMode.PAY_PER_REQUEST,
    });
  }
}

https://github.com/JohannesKonings/tanstack-aws/blob/main/lib/constructs/DatabaseTodos.ts

This table needs to be wired to the web app server Lambda.

In the web app construct, the table construct is added. The Lambda is allowed to read and write data to the table.

Concretely, that means (1) creating the table, (2) passing the table name into the server function, and (3) granting the function read/write permissions.

const databaseTodos = new DatabaseTodos(this, "DatabaseTodos");

const webappServer = new WebappServer(this, "WebappServer", {
  tableName: databaseTodos.dbTodos.tableName,
});

databaseTodos.dbTodos.grantReadWriteData(webappServer.webappServer);

https://github.com/JohannesKonings/tanstack-aws/blob/main/lib/constructs/Webapp.ts

The passed table name is exposed as an environment variable in the Lambda function.

This keeps the application code decoupled from CDK: the Lambda only needs to know an env var, and CDK is responsible for wiring that value at deploy time.

this.webappServer = new Function(this, "WebappServer", {
  code: Code.fromAsset(
    path.join(
      path.dirname(new URL(import.meta.url).pathname),
      "../../.output/server",
    ),
  ),
  // functionName: PhysicalName.GENERATE_IF_NEEDED,
  handler: "index.handler",
  memorySize: 2048,
  runtime: Runtime.NODEJS_24_X,
  // oxlint-disable-next-line no-magic-numbers
  timeout: Duration.seconds(60),
  environment: {
    DDB_TODOS_TABLE_NAME: tableName,
  },
});

https://github.com/JohannesKonings/tanstack-aws/blob/main/lib/constructs/WebappServer.ts

A DynamoDB Client

In this example, a simple wrapper around the DynamoDB client is used. In larger projects, something like https://electrodb.dev/ can help. This is the bridge from the API behind TanStack DB to DynamoDB.

The client below implements the four operations the demo needs: list todos, create a todo, update one or more todos, and delete todos in batches.

Here is the environment variable used for the table name.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import {
  BatchWriteCommand,
  DynamoDBDocumentClient,
  PutCommand,
  QueryCommand,
  UpdateCommand,
} from "@aws-sdk/lib-dynamodb";
import { type Todo, todoSchema, type TodoUpdate } from "@/webapp/types/todo";

const TODOS_PK = "TODO";
const TODOS_TABLE_ENV = "DDB_TODOS_TABLE_NAME";
const EMPTY_LENGTH = 0;
const INITIAL_ATTEMPT = 0;
const NEXT_ATTEMPT_INCREMENT = 1;
const MAX_RETRY_ATTEMPTS = 3;
const MAX_BATCH_WRITE_ITEMS = 25;

let ddbDocSingleton: DynamoDBDocumentClient | null = null;

export const getDdbDocClient = (): DynamoDBDocumentClient => {
  if (!ddbDocSingleton) {
    ddbDocSingleton = DynamoDBDocumentClient.from(new DynamoDBClient({}), {
      marshallOptions: {
        removeUndefinedValues: true,
      },
    });
  }

  return ddbDocSingleton;
};

export const requireEnvVar = (name: string): string => {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing env var: ${name}`);
  }

  return value;
};

export const getTodosTableName = (): string => requireEnvVar(TODOS_TABLE_ENV);

const todoSortKey = (id: number): string => `TODO#${id}`;

const parseTodoItem = (item: Record<string, unknown>): Todo | null => {
  const parsed = todoSchema.safeParse({
    id: item.id,
    name: item.name,
    status: item.status,
  });

  if (!parsed.success) {
    return null;
  }

  return parsed.data;
};

const chunkItems = <Item>(items: Item[], chunkSize: number): Item[][] => {
  const out: Item[][] = [];
  for (let index = EMPTY_LENGTH; index < items.length; index += chunkSize) {
    out.push(items.slice(index, index + chunkSize));
  }
  return out;
};

export type TodosDdbClient = {
  getTodos: () => Promise<Todo[]>;
  putTodo: (todo: Todo) => Promise<Todo>;
  updateTodos: (updates: TodoUpdate[]) => Promise<void>;
  deleteTodos: (ids: number[]) => Promise<void>;
};

const retryBatchWrite = async (args: {
  ddbDoc: DynamoDBDocumentClient;
  requestItems: unknown;
  attempt: number;
}): Promise<void> => {
  const response = await args.ddbDoc.send(
    new BatchWriteCommand({
      RequestItems: args.requestItems as never,
    }),
  );

  const unprocessedItems = response.UnprocessedItems;
  if (
    !unprocessedItems ||
    Object.keys(unprocessedItems).length === EMPTY_LENGTH
  ) {
    return;
  }

  if (args.attempt + NEXT_ATTEMPT_INCREMENT >= MAX_RETRY_ATTEMPTS) {
    return;
  }

  await retryBatchWrite({
    ddbDoc: args.ddbDoc,
    requestItems: unprocessedItems,
    attempt: args.attempt + NEXT_ATTEMPT_INCREMENT,
  });
};

export const createTodosDdbClient = (): TodosDdbClient => {
  const ddbDoc = getDdbDocClient();

  return {
    getTodos: async () => {
      const tableName = getTodosTableName();
      const result = await ddbDoc.send(
        new QueryCommand({
          TableName: tableName,
          KeyConditionExpression: "#pk = :pk",
          ExpressionAttributeNames: {
            "#pk": "pk",
          },
          ExpressionAttributeValues: {
            ":pk": TODOS_PK,
          },
        }),
      );

      const items = (result.Items ?? [])
        .map((item) => parseTodoItem(item))
        .filter((todo): todo is Todo => todo !== null);
      return items;
    },

    putTodo: async (todo: Todo) => {
      const tableName = getTodosTableName();
      await ddbDoc.send(
        new PutCommand({
          TableName: tableName,
          Item: {
            pk: TODOS_PK,
            sk: todoSortKey(todo.id),
            id: todo.id,
            name: todo.name,
            status: todo.status,
          },
        }),
      );

      return todo;
    },

    updateTodos: async (updates: TodoUpdate[]) => {
      const tableName = getTodosTableName();

      await Promise.all(
        updates.map(async (update) => {
          const sets: string[] = [];
          const names: Record<string, string> = {
            "#pk": "pk",
            "#sk": "sk",
          };
          const values: Record<string, unknown> = {};

          if (update.changes.name !== undefined) {
            names["#name"] = "name";
            values[":name"] = update.changes.name;
            sets.push("#name = :name");
          }

          if (update.changes.status !== undefined) {
            names["#status"] = "status";
            values[":status"] = update.changes.status;
            sets.push("#status = :status");
          }

          if (sets.length === EMPTY_LENGTH) {
            return;
          }

          try {
            await ddbDoc.send(
              new UpdateCommand({
                TableName: tableName,
                Key: {
                  pk: TODOS_PK,
                  sk: todoSortKey(update.id),
                },
                UpdateExpression: `SET ${sets.join(", ")}`,
                ConditionExpression:
                  "attribute_exists(#pk) AND attribute_exists(#sk)",
                ExpressionAttributeNames: names,
                ExpressionAttributeValues: values,
              }),
            );
          } catch (error) {
            const errorName = (error as { name?: string } | undefined)?.name;
            if (errorName !== "ConditionalCheckFailedException") {
              throw error;
            }
          }
        }),
      );
    },

    deleteTodos: async (ids: number[]) => {
      const tableName = getTodosTableName();
      const groups = chunkItems(ids, MAX_BATCH_WRITE_ITEMS);

      await Promise.all(
        groups.map(async (group) => {
          const requestItems = {
            [tableName]: group.map((id) => ({
              DeleteRequest: {
                Key: {
                  pk: TODOS_PK,
                  sk: todoSortKey(id),
                },
              },
            })),
          };

          await retryBatchWrite({
            ddbDoc,
            requestItems,
            attempt: INITIAL_ATTEMPT,
          });
        }),
      );
    },
  };
};

https://github.com/JohannesKonings/tanstack-aws/blob/main/src/webapp/integrations/ddb-client/ddbClient.ts

The API connection to DynamoDB

With the DynamoDB client created above, you can create an API that connects TanStack DB to DynamoDB.

In TanStack Start, this is a server route with standard HTTP verbs. The route validates input, calls the DynamoDB client, and returns JSON responses.

// oxlint-disable func-style
import { createFileRoute } from "@tanstack/react-router";
import { createTodosDdbClient } from "@/webapp/integrations/ddb-client/ddbClient";
import {
  createTodoRequestSchema,
  deleteTodosRequestSchema,
  updateTodosRequestSchema,
} from "@/webapp/types/todo";

const todosClient = createTodosDdbClient();

export const Route = createFileRoute("/demo/api/ddb-todos")({
  server: {
    handlers: {
      // oxlint-disable-next-line arrow-body-style
      GET: async () => {
        const items = await todosClient.getTodos();
        return Response.json(items);
      },
      POST: async ({ request }) => {
        const requestJson = await request.json();
        const todoParsed = createTodoRequestSchema.parse(requestJson);

        const saved = await todosClient.putTodo(todoParsed);
        return Response.json(saved);
      },
      PUT: async ({ request }) => {
        const requestJson = await request.json();
        const updates = updateTodosRequestSchema.parse(requestJson);

        await todosClient.updateTodos(updates);

        return Response.json({ ok: true });
      },
      DELETE: async ({ request }) => {
        const requestJson = await request.json();
        const ids = deleteTodosRequestSchema.parse(requestJson);

        await todosClient.deleteTodos(ids);

        return Response.json({ ok: true });
      },
    },
  },
});

https://github.com/JohannesKonings/tanstack-aws/blob/main/src/webapp/routes/demo/api.ddb-todos.ts

The TanStack DB collection

The collection uses the API to fetch and mutate data in DynamoDB.

This is the key integration point: the collection fetches via the queryFn, and the transaction callbacks (onInsert, onUpdate, onDelete) translate local writes into API calls.

import { queryCollectionOptions } from "@tanstack/query-db-collection";
import { createCollection } from "@tanstack/react-db";
import { getContext } from "@/webapp/integrations/tanstack-query/root-provider";
import { type Todo, todoSchema } from "../types/todo";

// const todoApiPath = '/demo/api/tq-todos';
const todoApiPath = "/demo/api/ddb-todos";
const api = {
  async fetchTodos(): Promise<Todo[]> {
    const response = await fetch(todoApiPath);
    if (!response.ok) {
      throw new Error("Failed to fetch todos");
    }
    const data = await response.json();
    return todoSchema.array().parse(data);
  },

  async createTodos(todo: Omit<Todo, "id">) {
    await fetch(todoApiPath, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(todo),
    });
  },

  async updateTodos(
    updates: { id: number; changes: Partial<Omit<Todo, "id">> }[],
  ) {
    await fetch(todoApiPath, {
      method: "PUT",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(updates),
    });
  },

  async deleteTodos(ids: number[]) {
    await fetch(todoApiPath, {
      method: "DELETE",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(ids),
    });
  },
};

export const todosCollection = createCollection(
  queryCollectionOptions<Todo>({
    queryKey: ["todos"],
    queryFn: () => api.fetchTodos(),
    queryClient: getContext().queryClient,
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => {
      const newItems = transaction.mutations.map((mutation) => ({
        id: Math.random(), // Temporary ID; real ID should be assigned by the server
        name: mutation.modified.name,
        status: mutation.modified.status,
      }));
      for (const item of newItems) {
        api.createTodos(item);
      }
    },
    onUpdate: async ({ transaction }) => {
      const updates = transaction.mutations.map((mutation) => ({
        id: mutation.key,
        changes: mutation.changes,
      }));
      await api.updateTodos(updates);
    },
    onDelete: async ({ transaction }) => {
      const ids = transaction.mutations.map((mutation) => mutation.key);
      await api.deleteTodos(ids);
    },
  }),
);

https://github.com/JohannesKonings/tanstack-aws/blob/main/src/webapp/db-collections/todos.ts

The hook

These hooks provide a small, UI-friendly API on top of the collection. Components can call addTodo/toggleTodoStatus/deleteTodo, and useTodos subscribes to the live query for rendering.

import { useLiveQuery } from "@tanstack/react-db";
// oxlint-disable func-style
import { todosCollection } from "@/webapp/db-collections/todos";
import type { Todo } from "../types/todo";

export function useTodo() {
  const addTodo = async ({ name, status }: Omit<Todo, "id">) => {
    // oxlint-disable-next-line no-magic-numbers
    const randomId = Math.floor(Math.random() * 1000000);
    todosCollection.insert({ id: randomId, name, status });
  };

  const toggleTodoStatus = (id: number, status: "pending" | "completed") => {
    todosCollection.update(id, (draft) => {
      if (draft) {
        draft.status = status;
      }
    });
  };

  const deleteTodo = (id: number) => {
    todosCollection.delete(id);
  };

  return { addTodo, toggleTodoStatus, deleteTodo };
}

export function useTodos() {
  const { data: todos } = useLiveQuery((todoQuery) =>
    todoQuery.from({ todo: todosCollection }).select(({ todo }) => ({
      ...todo,
    })),
  );

  return todos as Todo[];
}

https://github.com/JohannesKonings/tanstack-aws/blob/main/src/webapp/hooks/useDbTodos.ts

The component

Finally, the UI component is just a thin layer over the hooks: render the list, submit a new todo, toggle completion, and delete items.

// oxlint-disable func-style
import { createFileRoute } from "@tanstack/react-router";
import { Trash2 } from "lucide-react";
import { useState } from "react";
import { useTodo, useTodos } from "@/webapp/hooks/useDbTodos";

export const Route = createFileRoute("/demo/db-todo")({
  ssr: false,
  component: DbTodos,
});

function DbTodos() {
  const todos = useTodos();
  const { addTodo, toggleTodoStatus, deleteTodo } = useTodo();

  const [todo, setTodo] = useState<string>("");

  const submitTodo = () => {
    if (todo.trim() !== "") {
      addTodo({ name: todo, status: "pending" });
      setTodo("");
    }
  };

  const handleTodoStatusToggle = (todoItem: (typeof todos)[number]) => {
    if (todoItem.status === "completed") {
      toggleTodoStatus(todoItem.id, "pending");
    } else {
      toggleTodoStatus(todoItem.id, "completed");
    }
  };

  return (
    <div
      className="flex items-center justify-center min-h-screen bg-linear-to-br from-purple-100 to-blue-100 p-4 text-white"
      style={{
        backgroundImage:
          "radial-gradient(50% 50% at 95% 5%, #4a90c2 0%, #317eb9 50%, #1e4d72 100%)",
      }}
    >
      <div className="w-full max-w-2xl p-8 rounded-xl backdrop-blur-md bg-black/50 shadow-xl border-8 border-black/10">
        <h1 className="text-2xl mb-4">DB Todo list</h1>
        <ul className="mb-4 space-y-2">
          {todos?.map((todoItem) => {
            const isCompleted = todoItem.status === "completed";
            let textClasses = "";
            if (isCompleted) {
              textClasses = "line-through opacity-60";
            }
            return (
              <li
                key={todoItem.id}
                className="bg-white/10 border border-white/20 rounded-lg p-3 backdrop-blur-sm shadow-md flex items-center gap-3"
              >
                <input
                  type="checkbox"
                  checked={isCompleted}
                  onChange={() => handleTodoStatusToggle(todoItem)}
                  className="w-5 h-5 cursor-pointer accent-blue-400"
                />
                <span className={`text-lg text-white flex-1 ${textClasses}`}>
                  {todoItem.name}
                </span>
                <button
                  type="button"
                  onClick={() => deleteTodo(todoItem.id)}
                  className="text-white/80 hover:text-red-300 p-2 rounded-full hover:bg-white/10 transition-colors"
                  aria-label={`Delete todo ${todoItem.name}`}
                >
                  <Trash2 className="w-5 h-5" aria-hidden="true" />
                </button>
              </li>
            );
          })}
        </ul>
        <div className="flex flex-col gap-2">
          <input
            type="text"
            value={todo}
            onChange={(event) => setTodo(event.target.value)}
            onKeyDown={(event) => {
              if (event.key === "Enter") {
                submitTodo();
              }
            }}
            placeholder="Enter a new todo..."
            className="w-full px-4 py-3 rounded-lg border border-white/20 bg-white/10 backdrop-blur-sm text-white placeholder-white/60 focus:outline-none focus:ring-2 focus:ring-blue-400 focus:border-transparent"
          />
          <button
            // oxlint-disable-next-line no-magic-numbers
            disabled={todo.trim().length === 0}
            onClick={submitTodo}
            className="bg-blue-500 hover:bg-blue-600 disabled:bg-blue-500/50 disabled:cursor-not-allowed text-white font-bold py-3 px-4 rounded-lg transition-colors"
          >
            Add todo
          </button>
        </div>
      </div>
    </div>
  );
}

https://github.com/JohannesKonings/tanstack-aws/blob/main/src/webapp/routes/demo/db-todo.tsx

Result

Conclusion

This is a simple example and implementation of TanStack DB with DynamoDB on AWS. In a more complete example, you’d need to figure out how to map a single-table design in DynamoDB to multiple collections in TanStack DB.

From here, the next natural steps are adding authentication/authorization on the API, better id generation (server-assigned ids), and a more explicit data model to support multiple entity types.

Sources and References

Examples (full implementation on GitHub): github.com/JohannesKonings/tanstack-aws
TanStack DB documentation : tanstack.com/db/latest

Monitor multiple resources using a single CloudWatch Alarm (with CDK)

Johannes Konings — Sat, 13 Dec 2025 08:15:18 +0000

Introduction

CloudWatch Metrics Insights query alarms (aka “multi-metric alarms”) let one alarm evaluate many individual resources. You write a Metrics Insights SQL query (with GROUP BY), and CloudWatch keeps the alarm’s contributor set up to date as resources are created/deleted.

Before this announcement, you had two imperfect choices:

Create one alarm per resource (granular, but high maintenance as resources change).
Use aggregated metrics (low maintenance, but you lose per-resource visibility and actions).

The September 2025 feature (https://aws.amazon.com/about-aws/whats-new/2025/09/amazon-cloudwatch-alarm-multiple-metrics/) adds query alarms that evaluate many individual metrics with one alarm, preserving per-resource visibility and actions while removing the per-resource alarm sprawl.

Pubudu Jayawardana already described how to use it here https://pubudu.dev/posts/cloudwatch-multi-metric-alarms/, this post focuses on how to implement the pattern in AWS CDK with concise, working examples (SQS DLQs with tag-based queries, and SFN across all state machines).

Account Configuration

If you want WHERE tag.X = 'Y' filters in Metrics Insights queries, enable resource tags on telemetry: https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/EnableResourceTagsOnTelemetry.html

As of 2025-12, this setting isn’t exposed as a CloudFormation resource. CloudWatch may take up to a few hours to fully enrich all metrics after enabling.

CLI equivalent:

aws observabilityadmin start-telemetry-enrichment

If you want this in CDK, use a Lambda-backed custom resource that calls the same API:

// https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/observabilityadmin/command/StartTelemetryEnrichmentCommand/
// https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/EnableResourceTagsOnTelemetry.html
new AwsCustomResource(this, "StartTelemetryEnrichment", {
  onCreate: {
    service: "@aws-sdk/client-observabilityadmin",
    action: "StartTelemetryEnrichment",
    physicalResourceId: PhysicalResourceId.of("StartTelemetryEnrichment"),
  },
  installLatestAwsSdk: true,
  // policy: AwsCustomResourcePolicy.fromSdkCalls({ resources: AwsCustomResourcePolicy.ANY_RESOURCE }),
  policy: AwsCustomResourcePolicy.fromStatements([
    new PolicyStatement({
      effect: Effect.ALLOW,
      actions: [
        "observabilityadmin:StartTelemetryEnrichment",
        "iam:CreateServiceLinkedRole",
        "resource-explorer-2:CreateIndex",
        "resource-explorer-2:CreateManagedView",
        "resource-explorer-2:CreateStreamingAccessForService",
      ],
      resources: ["*"],
    }),
  ]),
});

Example 1: one alarm for all DLQs (tag filtered)

Tag only the DLQs you want included (opt-in):

const dlq1 = new Queue(this, "DLQ1");
Tags.of(dlq1).add("isDlq", "true");
Tags.of(dlq1).add("monitor", "true");
new Queue(this, "Queue1", {
  deadLetterQueue: {
    queue: dlq1,
    maxReceiveCount: 3,
  },
});

const dlq2 = new Queue(this, "DLQ2");
Tags.of(dlq2).add("isDlq", "true");
Tags.of(dlq2).add("monitor", "true");
new Queue(this, "Queue2", {
  deadLetterQueue: {
    queue: dlq2,
    maxReceiveCount: 5,
  },
});

const dlq3 = new Queue(this, "DLQ3");
Tags.of(dlq3).add("isDlq", "true");
Tags.of(dlq3).add("monitor", "false");
new Queue(this, "Queue3", {
  deadLetterQueue: {
    queue: dlq3,
    maxReceiveCount: 5,
  },
});


const expressionDlq = new MathExpression({
  expression: `SELECT MAX(ApproximateNumberOfMessagesVisible)
            FROM SCHEMA("AWS/SQS", QueueName)
            WHERE tag.monitor = 'true'
            AND tag.isDlq = 'true'
            GROUP BY QueueName
            ORDER BY COUNT() DESC`,
  usingMetrics: {},
  period: Duration.minutes(1),
  label: "DLQ messages",
});

new Alarm(this, "DlqAlarm", {
  metric: expressionDlq,
  threshold: 1,
  evaluationPeriods: 1,
  comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
  alarmDescription: "Alarm if any tagged DLQ has visible messages",
  alarmName: "DLQ-Alarm",
});

Example 2: one alarm for failed Step Functions executions

Tag filtering only works for resource types supported by resource tags for telemetry (SQS is supported; Step Functions isn’t listed): https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/UsingResourceTagsForTelemetry.html#SupportedAWSInfrastructureMetrics

So for Step Functions, this alarms across all state machines in the account/region.

const sfn1 = new StateMachine(this, "StateMachine1", {
  definitionBody: DefinitionBody.fromChainable(new Fail(this, "FailState1")),
});

const sfn2 = new StateMachine(this, "StateMachine2", {
  definitionBody: DefinitionBody.fromChainable(new Fail(this, "FailState2")),
});


const expressionSfn = new MathExpression({
  expression: `SELECT MAX(ExecutionsFailed)
            FROM SCHEMA("AWS/States", StateMachineName)
            GROUP BY StateMachineName
            ORDER BY COUNT() DESC`,
  usingMetrics: {},
  period: Duration.minutes(1),
  label: "Sfn failed executions",
});

new Alarm(this, "SfnAlarm", {
  metric: expressionSfn,
  threshold: 1,
  evaluationPeriods: 1,
  comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
  alarmDescription: "Alarm if any state machine has failed executions",
  alarmName: "SFN-Alarm",
});

Sources

Feature announcement: https://aws.amazon.com/about-aws/whats-new/2025/09/amazon-cloudwatch-alarm-multiple-metrics/
CloudWatch docs (alarms on Metrics Insights queries): https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-metrics-insights-alarms.html
CloudWatch docs (create a Metrics Insights alarm): https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-metrics-insights-alarm-create.html
CloudWatch docs (enable resource tags on telemetry): https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/EnableResourceTagsOnTelemetry.html
CloudWatch docs (supported resources for tag enrichment): https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/UsingResourceTagsForTelemetry.html#SupportedAWSInfrastructureMetrics
CloudWatch docs (Metrics Insights quotas, incl. 500 time series limit): https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-metrics-insights-limits.html
Background article: https://pubudu.dev/posts/cloudwatch-multi-metric-alarms/

Use cdk-notifier to check CloudFormation predeployment validations in pull requests

Johannes Konings — Sat, 06 Dec 2025 08:15:18 +0000

Overview

This post builds on the previous example on using cdk-notifier to compare changes in pull requests. It demonstrates how to extend the workflow by adding CloudFormation change set validation alongside cdk diff to provide more comprehensive pre-deployment validation.

This approach leverages CloudFormation's pre-deployment validation capabilities, which are detailed in AWS's blog post on Accelerate infrastructure development with CloudFormation pre-deployment validation and simplified troubleshooting.

Use Case

The cdk diff via the cdk-notifier in pull requests helps a lot to understand what will happen after the merge, but not all deployment issues can be identified with the diff alone.

For example, adding a role with the same name as an existing role in the account will lead to a deployment failure, but this is not visible in the diff.

Also, adding multiple Global Secondary Indexes (GSIs) to an existing DynamoDB table in one deployment will fail, but the diff does not show this limitation. ⚠️ Unfortunately, I didn't manage to raise this problem in the deployment validation.

The Extended Example

This example enhances the original feature stacks scenario with two key additions:

Infrastructure Changes

The example adds:

Global Secondary Indexes (GSIs) to the DynamoDB table
CloudWatch LogGroup to the stack

import { App, Stack, StackProps, aws_dynamodb as dynamodb } from "aws-cdk-lib";
import { LogGroup } from "aws-cdk-lib/aws-logs";
import { Construct } from "constructs";

export class CdkNotfifierFeatureStackExample extends Stack {
  constructor(scope: Construct, id: string, props: StackProps = {}) {
    super(scope, id, props);

    const table = new dynamodb.Table(this, "Table", {
      tableName: `Table-${branchName}`,
      partitionKey: { name: "id", type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
    });

    // Add CloudWatch LogGroup
    new LogGroup(this, "LogGroup", {
      logGroupName: "alreadyexisting",
    });

    // Add GSI 1
    table.addGlobalSecondaryIndex({
      indexName: "GSI1",
      partitionKey: { name: "gsi1pk", type: dynamodb.AttributeType.STRING },
      sortKey: { name: "gsi1sk", type: dynamodb.AttributeType.STRING },
    });

    // Add GSI 2
    table.addGlobalSecondaryIndex({
      indexName: "GSI2",
      partitionKey: { name: "gsi2pk", type: dynamodb.AttributeType.STRING },
      sortKey: { name: "gsi2sk", type: dynamodb.AttributeType.STRING },
    });
  }
}

const app = new App();

const branchName = process.env.BRANCH_NAME || "dev";
console.log(`Deploying with stack postfix ${branchName}`);

new CdkNotfifierFeatureStackExample(
  app,
  `cdk-notifier-feature-stacks-${branchName}`,
);

app.synth();

Extended GitHub Action Workflow

The workflow now performs both cdk diff and cdk deploy --method prepare-change-set. These command results are aggregated into a single log file, which is then processed by cdk-notifier to create a comprehensive report.

- name: Check diff and change-set to main
  run: |
    pnpm install --frozen-lockfile  
    ECHO=$(echo "## Check the diff to main")
    echo $ECHO | tee -a cdk.log
    NPM_CONFIG_LOGLEVEL=error BRANCH_NAME=main pnpm exec cdk diff --progress=events &> >(tee -a cdk.log)
    ECHO=$(echo "## Check the change-set to main")
    echo $ECHO | tee -a cdk.log
    NPM_CONFIG_LOGLEVEL=error BRANCH_NAME=main pnpm exec cdk deploy --all --method prepare-change-set &> >(tee -a cdk.log) || true
    echo "create cdk-notifier report"
    echo "BRANCH_NAME: $BRANCH_NAME"
    echo "GITHUB_OWNER: $GITHUB_OWNER"
    echo "GITHUB_REPO: $GITHUB_REPO"
    cdk-notifier \
    --owner ${{ env.GITHUB_OWNER }} \
    --repo ${{ env.GITHUB_REPO }} \
    --token ${{ secrets.GITHUB_TOKEN }} \
    --log-file ./cdk.log \
    --tag-id diff-to-main \
    --pull-request-id ${{ env.PULL_REQUEST_ID }} \
    --vcs github \
    --ci circleci \
    --template extendedWithResources

Results in the Pull Request:

Deployment Error with Multiple GSIs

When trying to deploy multiple GSIs to an existing table, the deployment validation will show the error:

Further Enhancements

Future improvements could include: checking the change set via the AWS CLI to describe the change set to get more detailed information about the changes planned by CloudFormation.

aws cloudformation describe-change-set

Nice to Have (if not overlooked)

The cdk diff creates by default a change set, which could be reported back in the diff

Code and References

Full example repository: https://github.com/JohannesKonings/cdk-notifier-examples
Related PR with changes: https://github.com/JohannesKonings/cdk-notifier-examples/pull/12
cdk-notifier project: https://github.com/karlderkaefer/cdk-notifier

For the foundational concepts behind this example, refer to the earlier post: Use cdk-notifier to compare changes in pull requests

Deploy TanStack Start serverless on AWS

Johannes Konings — Sun, 30 Nov 2025 08:15:18 +0000

Introduction

This guide demonstrates how to deploy a TanStack Start application on AWS using a serverless architecture. TanStack Start is a full-stack React framework that provides server-side rendering, routing, and data fetching capabilities. We'll deploy it using AWS Lambda, API Gateway with streaming support, CloudFront for CDN, and S3 for static assets.

The complete implementation is available in the tanstack-aws repository, which serves as a working example and template for this deployment pattern.

Disclaimer

This is a straightforward implementation guide focused on the core deployment architecture. It does not cover production best practices such as WAF, comprehensive monitoring, structured logging, automated CI/CD pipelines, or security hardening. Use this as a starting point and extend it with production-grade features as needed.

Architecture

The deployment architecture consists of the following AWS services:

AWS Lambda : Runs the TanStack Start server-side rendering with Node.js 24.x runtime
API Gateway (REST API): Provides HTTP endpoint with streaming support for Lambda responses
CloudFront : CDN for distributing both dynamic and static content globally
S3 : Hosts static assets (JavaScript, CSS, images) generated during build
IAM : Manages permissions for Lambda to access AWS Bedrock (for AI features)

The architecture leverages streaming responses through API Gateway, which is essential for server-side rendering and AI-powered features that stream content to the client.

Implementation Steps

Create the TanStack Start App

Start by creating a new TanStack Start application using the official CLI as described in the TanStack Start Quick Start:

npm create @tanstack/start

When prompted, select Nitro as the deployment adapter since it provides a built-in AWS Lambda preset with streaming support.

Organize Project Structure

Move the generated TanStack application files to a src/webapp directory to separate the web application from the infrastructure code. This allows you to maintain both the CDK infrastructure and the application in the same repository.

Reference : See the project structure in tanstack-aws repository

Configure Vite and Nitro

Update your vite.config.ts to configure Nitro for AWS Lambda deployment with streaming enabled. This configuration is crucial for enabling response streaming:

Reference : vite.config.ts

const config = defineConfig({
  plugins: [
    devtools(),
    nitro({
      awsLambda: { streaming: true },
      preset: "aws-lambda",
    }),
    viteTsConfigPaths({
      projects: ["./tsconfig.json"],
    }),
    tailwindcss(),
    tanstackStart({
      srcDirectory: "src/webapp",
    }),
    viteReact(),
  ],
});

Key configuration points:

awsLambda: { streaming: true }: Enables response streaming for Lambda
preset: 'aws-lambda': Uses Nitro's AWS Lambda adapter
srcDirectory: 'src/webapp': Points to the application source directory

Set Up AWS CDK Infrastructure

You can maintain the CDK infrastructure code in the same repository as your application. The infrastructure uses several custom constructs to deploy the complete stack.

Reference : All constructs are in lib/constructs/

Webapp Server Lambda

Create a Lambda function construct that deploys the Nitro build output. The Lambda function runs the server-side rendering and API endpoints.

Reference : lib/constructs/WebappServer.ts

import { Code, Function, Runtime } from "aws-cdk-lib/aws-lambda";
import { Duration, Tags } from "aws-cdk-lib";
import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
import { Construct } from "constructs";
import path from "node:path";

export class WebappServer extends Construct {
  readonly webappServer: Function;

  constructor(scope: Construct, id: string) {
    super(scope, id);

    this.webappServer = new Function(this, "WebappServer", {
      code: Code.fromAsset(
        path.join(
          path.dirname(new URL(import.meta.url).pathname),
          "../../.output/server",
        ),
      ),
      handler: "index.handler",
      memorySize: 2048,
      runtime: Runtime.NODEJS_24_X,
      timeout: Duration.seconds(60),
    });
    Tags.of(this.webappServer).add("IsWebAppServer", "true");

    this.webappServer.addToRolePolicy(
      new PolicyStatement({
        actions: [
          "bedrock:InvokeModel",
          "bedrock:InvokeModelWithResponseStream",
        ],
        effect: Effect.ALLOW,
        resources: ["*"],
      }),
    );
  }
}

Important details:

Code source : Points to .output/server generated by Nitro's build process (nitro build)
Handler : index.handler is the default entry point created by Nitro
Memory : 2048 MB provides adequate resources for SSR operations
Runtime : Node.js 24.x for latest features and performance
Bedrock permissions : Added for AI chat functionality (optional, remove if not needed)

Assets Bucket and Deployment

Create an S3 bucket to host static assets generated during the build process:

Reference : lib/constructs/WebappAssetsBucket.ts

import { Bucket } from "aws-cdk-lib/aws-s3";
import { Construct } from "constructs";

export class WebappAssetsBucket extends Construct {
  readonly assetsBucket: Bucket;
  constructor(scope: Construct, id: string) {
    super(scope, id);

    this.assetsBucket = new Bucket(this, "AssetsBucket");
  }
}

Use the BucketDeployment construct to automatically upload static assets to S3 after each build and invalidate the CloudFront cache:

Reference : lib/constructs/WebappAssetsDeployment.ts

import { BucketDeployment, Source } from "aws-cdk-lib/aws-s3-deployment";
import { Bucket } from "aws-cdk-lib/aws-s3";
import { Construct } from "constructs";
import type { Distribution } from "aws-cdk-lib/aws-cloudfront";
import path from "node:path";

type WebappAssetsDeploymentProps = {
  assetsBucket: Bucket;
  distribution: Distribution;
};

export class WebappAssetsDeployment extends Construct {
  constructor(
    scope: Construct,
    id: string,
    props: WebappAssetsDeploymentProps,
  ) {
    super(scope, id);

    const { assetsBucket, distribution } = props;

    const sourcePath = path.join(
      path.dirname(new URL(import.meta.url).pathname),
      "../../.output/public",
    );

    new BucketDeployment(this, "AssetBucketDeployment", {
      destinationBucket: assetsBucket,
      distribution,
      distributionPaths: ["/*"],
      sources: [Source.asset(sourcePath)],
    });
  }
}

Key features:

Source : Points to .output/public where Nitro generates static assets
Cache invalidation : distributionPaths: ["/*"] invalidates CloudFront cache on deployment
Automatic deployment : Runs during CDK deployment to sync assets

API Gateway with Streaming

Create a REST API Gateway that integrates with the Lambda function and enables streaming responses:

Reference : lib/constructs/WebappApi.ts

import {
  EndpointType,
  LambdaRestApi,
  ResponseTransferMode,
} from "aws-cdk-lib/aws-apigateway";
import { Construct } from "constructs";
import { Function } from "aws-cdk-lib/aws-lambda";

type WebappApiProps = {
  webappServer: Function;
};

export class WebappApi extends Construct {
  readonly webappApi: LambdaRestApi;

  constructor(scope: Construct, id: string, props: WebappApiProps) {
    super(scope, id);

    const { webappServer } = props;

    this.webappApi = new LambdaRestApi(this, "WebappApi", {
      endpointConfiguration: {
        types: [EndpointType.REGIONAL],
      },
      handler: webappServer,
      integrationOptions: {
        responseTransferMode: ResponseTransferMode.STREAM,
      },
    });
  }
}

Critical configuration:

ResponseTransferMode.STREAM : Enables streaming responses from Lambda, essential for SSR and AI streaming
LambdaRestApi : Automatically creates proxy integration for all routes

CloudFront Distribution

Set up CloudFront to serve both dynamic content (from API Gateway) and static assets (from S3):

Reference : lib/constructs/WebappDistribution.ts

import {
  AllowedMethods,
  CachePolicy,
  Distribution,
  OriginRequestPolicy,
  PriceClass,
  ResponseHeadersPolicy,
  ViewerProtocolPolicy,
} from "aws-cdk-lib/aws-cloudfront";
import { Construct } from "constructs";
import {
  RestApiOrigin,
  S3BucketOrigin,
} from "aws-cdk-lib/aws-cloudfront-origins";
import type { Bucket } from "aws-cdk-lib/aws-s3";
import type { RestApi } from "aws-cdk-lib/aws-apigateway";

type DistributionProps = {
  webappServerApi: RestApi;
  assetsBucket: Bucket;
};

export class WebappDistribution extends Construct {
  public readonly distribution: Distribution;

  constructor(scope: Construct, id: string, props: DistributionProps) {
    super(scope, id);

    const { webappServerApi, assetsBucket } = props;

    const s3BucketOrigin = S3BucketOrigin.withOriginAccessControl(assetsBucket);

    const defaultBehavior = {
      allowedMethods: AllowedMethods.ALLOW_ALL,
      cachePolicy: CachePolicy.CACHING_DISABLED,
      origin: new RestApiOrigin(webappServerApi),
      originRequestPolicy: OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER,
      responseHeadersPolicy: ResponseHeadersPolicy.SECURITY_HEADERS,
      viewerProtocolPolicy: ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
    };

    const staticAssetBehavior = {
      cachePolicy: CachePolicy.CACHING_OPTIMIZED,
      origin: s3BucketOrigin,
      viewerProtocolPolicy: ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
    };

    this.distribution = new Distribution(this, "Distribution", {
      additionalBehaviors: {
        "/assets/*": staticAssetBehavior,
        "/favicon.ico": staticAssetBehavior,
        "/images/*": staticAssetBehavior,
        "/site.webmanifest": staticAssetBehavior,
      },
      defaultBehavior,
      priceClass: PriceClass.PRICE_CLASS_100,
    });
  }
}

Key configuration:

Default behavior : Routes all requests to API Gateway with caching disabled (for dynamic SSR content)
Additional behaviors : Routes specific paths (/assets/*, /images/*, etc.) to S3 with optimized caching
Origin Access Control : Uses OAC (recommended over OAI) for secure S3 access
Security headers : Automatically adds security headers to responses
Price class : PRICE_CLASS_100 uses edge locations in North America and Europe (adjust as needed)

Wire Everything Together

Create a main construct that integrates all the components:

Reference : lib/constructs/Webapp.ts

import { Construct } from "constructs";
import { WebappDistribution } from "./WebappDistribution.ts";
import { WebappServer } from "./WebappServer.ts";
import { WebappAssetsDeployment } from "./WebappAssetsDeployment.ts";
import { WebappAssetsBucket } from "./WebappAssetsBucket.ts";
import { WebappApi } from "./WebappApi.ts";

export class Webapp extends Construct {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    const webappServer = new WebappServer(this, "WebappServer");

    const webappApi = new WebappApi(this, "WebappApi", {
      webappServer: webappServer.webappServer,
    });

    const assetsBucket = new WebappAssetsBucket(this, "WebappAssetsBucket");

    const distribution = new WebappDistribution(this, "WebappDistribution", {
      assetsBucket: assetsBucket.assetsBucket,
      webappServerApi: webappApi.webappApi,
    });

    new WebappAssetsDeployment(this, "WebappAssetsDeployment", {
      assetsBucket: assetsBucket.assetsBucket,
      distribution: distribution.distribution,
    });
  }
}

This construct orchestrates the deployment by:

Creating the Lambda function with the server code
Setting up API Gateway to route requests to Lambda
Creating the S3 bucket for static assets
Configuring CloudFront distribution with proper routing
Deploying static assets and invalidating the cache

Build and Deploy

To build and deploy the application:

# Install dependencies
pnpm install

# Build the TanStack Start application
pnpm webapp:build

# Deploy the CDK stack
pnpm cdk deploy

Reference : See package.json for all available scripts

Build process:

pnpm webapp:build runs vite build, which uses Nitro to compile the app
Nitro generates two outputs:
- .output/server/ - Lambda function code
- .output/public/ - Static assets
CDK deployment packages the Lambda code and uploads static assets to S3

Results

After deployment, you'll receive a CloudFront URL where your application is accessible. The architecture provides:

Fast global delivery : CloudFront CDN serves content from edge locations
Efficient caching : Static assets cached at edge, dynamic content from Lambda
Streaming support : Real-time responses for SSR and AI features
Scalability : Auto-scaling Lambda functions handle traffic spikes

Example Deployment

The template repository includes a demo chat application powered by AWS Bedrock (Claude AI) with streaming responses:

Key Dependencies

The implementation relies on these main packages (see package.json for exact versions):

TanStack ecosystem:

@tanstack/react-start - Full-stack React framework
@tanstack/react-router - File-based routing
@tanstack/react-query - Data fetching and caching
@tanstack/store - State management

Build tools:

nitro - Universal JavaScript server with AWS Lambda preset
vite - Frontend build tool
tailwindcss - Utility-first CSS framework

AWS infrastructure:

aws-cdk-lib - AWS Cloud Development Kit
constructs - CDK construct library

Alternative Deployment Options

While this guide focuses on API Gateway, the template repository also demonstrates Lambda Function URLs as an alternative origin. Function URLs provide a simpler setup but may require additional configuration for authentication (e.g., Lambda@Edge for SigV4 signing).

Note : The commented code in the reference implementation shows the Function URL approach for comparison.

Sources and References

Template repository : github.com/JohannesKonings/tanstack-aws
TanStack Start : tanstack.com/start
Nitro framework : nitro.unjs.io
AWS CDK : docs.aws.amazon.com/cdk
Inspired by : github.com/zhe/tanstack-start-aws-cdk

Encrypt All Lambda Environment Variables with AWS CDK Aspects/Mixins

Johannes Konings — Fri, 28 Nov 2025 08:15:18 +0000

Introduction

If you need to ensure that all AWS Lambda environment variables are encrypted with a customer-managed KMS key for compliance or security requirements, you can achieve this using AWS CDK aspects or mixins.

While Lambda functions that you create directly can be configured with the environmentEncryption property, third-party libraries or construct libraries may create Lambda functions where you don't have direct control over their configuration.

In such cases, you can use aspects or mixins to enforce encryption on all Lambda functions in your CDK app, regardless of how they were created.

Aspect, Property Injection or Mixin?

Aspects are a way to modify the CDK synth result on a L1 level after the constructs have been created. They are executed during the Prepare phase of the CDK lifecycle, after all constructs are created.

Property Injection is a way to modify the properties of L2 constructs before they are instantiated. Property injection happens during the Construct phase, at the time each construct is created.

Mixins can be used to modify constructs at any level (L1, L2, or L3). They are executed immediately when applied, unlike Aspects which execute later during synthesis.

Implementation

The stack look like this:

export class StackMain extends Stack {
  readonly encryptionKey: Key;

  constructor(scope: Construct, id: string, props: StackMainProps) {
    super(scope, id, props);

    this.encryptionKey = new Key(this, "EncryptionKey", {
      enableKeyRotation: true,
    });

    // Direct Lambda - environment encryption can be set directly
    new Function(this, "MyFunction", {
      code: Code.fromInline(
        'exports.handler = async function(event, context) { return "Hello World"; };',
      ),
      handler: "index.handler",
      runtime: Runtime.NODEJS_LATEST,
      environmentEncryption: this.encryptionKey,
      environment: {
        DUMMY: "dummy",
      },
    });

    // Indirect Lambda from third-party library - environment encryption cannot be controlled directly
    // Note: This is a hypothetical third-party construct for demonstration purposes
    new Lambda(this, "DummyThirdPartyLambda");
  }
}

The app could look like this (using either Aspect or Mixin):

const app = new App();
const stack = new StackMain(app, "StackMain", {});

// Option 1: Use Aspect (recommended for production - stable API)
Aspects.of(app).add(
  new LambdaEnvEncryptionSetterAspect(stack.encryptionKey.keyArn),
);

// Option 2: Use Mixin (developer preview - more flexible but API may change)
// Mixins.of(app).apply(
// new LambdaEnvEncryptionSetterMixin(stack.encryptionKey.keyArn),
// );

// could not be used because the functions are created before the property injection happens, but the key is needed for the injection
// PropertyInjectors.of(app).add(
// new LambdaEnvEncryptionSetterAspectPropertyInjection(stack.encryptionKey),
// );

Aspect

Here is an example of an aspect that encrypts all Lambda environment variables. This aspect operates on L1 (CfnFunction) constructs and sets the kmsKeyArn property during the synthesis Prepare phase:

import type { IAspect } from "aws-cdk-lib";
import { CfnFunction } from "aws-cdk-lib/aws-lambda";
import type { IConstruct } from "constructs";

export class LambdaEnvEncryptionSetterAspect implements IAspect {
  public readonly kmsKeyArn: string;

  constructor(kmsKeyArn: string) {
    this.kmsKeyArn = kmsKeyArn;
  }

  visit(node: IConstruct): void {
    if (node instanceof CfnFunction) {
      node.kmsKeyArn = this.kmsKeyArn;
    }
  }
}

Property Injector

Property Injection cannot be used in this specific case because:

Property Injection only works with L2 constructs (like lambda.Function), not L1 constructs (like lambda.CfnFunction)
Third-party libraries might create L1 constructs directly, bypassing the L2 construct layer
Creating the KMS key in the same stack while trying to inject it creates a timing issue, as injection happens during construct instantiation

Here's what the code would look like if you could use it (for reference only):

import { type InjectionContext, type IPropertyInjector } from "aws-cdk-lib";
import { IKey } from "aws-cdk-lib/aws-kms";
import { Function, FunctionProps } from "aws-cdk-lib/aws-lambda";

export class LambdaEnvEncryptionSetterPropertyInjector
  implements IPropertyInjector
{
  public readonly constructUniqueId: string;

  constructor(private readonly key: IKey) {
    this.constructUniqueId = Function.PROPERTY_INJECTION_ID;
  }

  public inject(
    originalProps: FunctionProps,
    _context: InjectionContext,
  ): FunctionProps {
    return {
      ...originalProps,
      environmentEncryption: this.key,
    };
  }
}

Mixin

Mixins are currently in developer preview (as of November 2025). Unlike Aspects, Mixins are applied immediately when called, giving you more control over when and how changes are applied. Here is an example of a mixin that encrypts all Lambda environment variables:

import { Mixin } from "@aws-cdk/mixins-preview/core";
import "@aws-cdk/mixins-preview/with";
import { IConstruct } from "constructs";
import { CfnFunction } from "aws-cdk-lib/aws-lambda";

export class LambdaEnvEncryptionSetterMixin implements Mixin {
  private readonly kmsKeyArn: string;

  constructor(kmsKeyArn: string) {
    this.kmsKeyArn = kmsKeyArn;
  }

  public supports(construct: IConstruct): boolean {
    return construct instanceof CfnFunction;
  }

  public applyTo(construct: IConstruct): IConstruct {
    if (construct instanceof CfnFunction) {
      construct.kmsKeyArn = this.kmsKeyArn;
    }

    return construct;
  }
}

Conclusion

Using AWS CDK aspects or mixins, you can enforce encryption on all AWS Lambda environment variables in your CDK app, even when using third-party libraries that create Lambda functions. This approach ensures that your Lambda functions adhere to security best practices without requiring direct control over their configuration.

Which Approach to Use?

Based on the AWS CDK Mixins RFC, the recommended usage is:

Aspects : Use for validation and compliance enforcement. This is the stable, production-ready approach.
Mixins : Use for making changes to constructs. However, since Mixins are still in Developer Preview, the API may change.

Recommendation for Production : Use Aspects for now, as they provide a stable API and are specifically designed for this type of cross-cutting concern. Once Mixins reach general availability, they may offer additional benefits for construct composition.

Sources

Granular statement cdk-nag AwsSolutions-IAM5 Suppressions

Johannes Konings — Thu, 27 Nov 2025 08:15:18 +0000

Overview

cdk-nag’s AwsSolutions-IAM5 rule is one of the most frequent findings in real-world stacks. It flags wildcard permissions in both Action (e.g., kms:GenerateDataKey*) and Resource (e.g., *) when there is no evidence-backed suppression. The challenge is that some AWS APIs are designed to require * (e.g., AWS X-Ray). Blanket suppressions hide too much. This post demonstrates how to record granular evidence specifically for actions that require *, ensuring that all other findings remain active.

Understanding the Problem

Why IAM5 triggers

You’ll hit AwsSolutions-IAM5 when a policy uses an asterisk ("*") in the resource or wildcards in actions. This is beneficial because least privilege is critical. However, several AWS APIs require * by design, or you might initially group actions broadly before refining the scope. Common examples include:

new PolicyStatement({
  actions: ["xray:PutTelemetryRecords", "xray:PutTraceSegments"],
  resources: ["*"],
  effect: Effect.ALLOW,
});


new PolicyStatement({
        actions: ["kms:GenerateDataKey*", "kms:ReEncrypt*"],
        resources: [
          "arn:aws:kms:eu-central-1:471112809534:key/a096e96c-780e-48eb-993b-5b8cc46d8fd7",
        ],
        effect: Effect.ALLOW,
      }),

Example Failure

An IAM5 failure typically looks like this:

[Error at /StackMain/MyRole/Policy/Resource] AwsSolutions-IAM5[Resource::*]: The IAM entity contains wildcard permissions and does not have a cdk-nag rule suppression with evidence for those permissions.

Why blanket suppression isn't enough

Suppressing the entire resource or the entire rule hides legitimate issues and loses the evidence that auditors expect. The goal is to:

Keep the rule active for statements that can be scoped.
Provide explicit evidence for the few actions that require *.

// Bad: over-broad, hides everything
NagSuppressions.addResourceSuppressions(role, [
  { id: "AwsSolutions-IAM5", reason: "needs wildcard" },
]);

This approach makes reviews harder and weakens the principle of least privilege.

The Solution

Overview

The solution involves using granular suppressions that document exactly which actions require * and why. Everything else remains flagged by cdk-nag. Thecdk-nag-custom-nag-pack automates this by:

Inspecting policy statements with *.
Adding a single AwsSolutions-IAM5 suppression per resource with appliesTo evidence for only those actions.
Leaving non-allowed wildcard actions reported so you can scope them properly.

Implementation

The repository includes a dedicated helper (iam5NagSuppressions.ts) that applies these granular suppressions automatically. The essential components are:

Statement scanning : Iterates IAM policy statements and selects those with Resource: * (including arrays that contain *).
Evidence builder : Produces appliesTo entries for Resource::* and only the allow-listed Action::<service:operation> values present in the statement.
Targeting : Attaches a single AwsSolutions-IAM5 suppression to each IAM Policy construct via its path, leaving any non-allowed wildcard actions unsuppressed (so they continue to fail until scoped).

You can find the source code here: iam5NagSuppressions.ts

Critical Difference: String-Based vs. Statement-Based Suppressions

Important: There are two fundamentally different approaches to granular IAM5 suppressions, each offering different levels of safety:

1. cdk-nag's Built-in `appliesTo`

The standard cdk-nag approach (see Example 6 in the cdk-nag docs) relies on string patterns:

NagSuppressions.addResourceSuppressions(
  lambda,
  [
    {
      id: "AwsSolutions-IAM5",
      reason: "X-Ray requires wildcard",
      appliesTo: ["Resource::*"],
    },
  ],
  true,
);

The Problem: This suppresses Resource::* and the specified actions anywhere they appear in the construct tree. If you later add a new policy statement like:

// This will be silently suppressed!
new PolicyStatement({
  actions: ["xray:PutTelemetryRecords"], // Matches the suppression
  resources: ["*"], // Matches the suppression
  effect: Effect.ALLOW,
});

The suppression hides it because the strings match , even though this might be an unintended permission you added months later.

2. cdk-nag-custom-nag-pack's Statement Validation

The cdk-nag-custom-nag-pack approach requires exact statement matching:

const policyStatementForSuppression: PolicyStatementProps = {
  actions: ["xray:PutTelemetryRecords", "xray:PutTraceSegments"],
  resources: ["*"],
  effect: Effect.ALLOW,
};

Iam5NagSuppressions.addIam5StatementResourceSuppressions(
  lambda,
  {
    id: "AwsSolutions-IAM5",
    reason: "X-Ray requires wildcard",
    appliesTo: [policyStatementForSuppression],
  },
  true,
);

The Benefit: The suppression applies only if there is an exact match of the entire policy statement (Effect, Actions, Resources). If you add a new statement with different actions or resources later:

// This will NOT be suppressed - it will be flagged!
new PolicyStatement({
  actions: ["xray:PutTelemetryRecords", "s3:*"], // Different actions
  resources: ["*"],
  effect: Effect.ALLOW,
});

It will be flagged because the statement does not match exactly. This prevents the accidental hiding of new wildcards added over time.

Key Takeaway: The cdk-nag-custom-nag-pack method validates the complete policy statement structure, whereas cdk-nag's built-in appliesTo relies on string patterns that may inadvertently suppress unrelated future wildcards.

Benefits

This statement-based approach:

Documents exactly why * is needed for specific AWS APIs
Keeps AwsSolutions-IAM5 active for everything else
Produces review-ready evidence via appliesTo
Prevents accidental suppression of future wildcard permissions

Lambda Construct Wildcard Scenario

The aws-lambda.Function construct (and its default execution role or managed policies) often introduces unavoidable wildcard permissions, such as those required for CloudWatch Logs creation or X-Ray tracing.

The Risk: If you suppress AwsSolutions-IAM5 broadly at the Function or Role level, you inadvertently hide every future wildcard you might add (e.g., s3:* or dynamodb:*).

The Granular Strategy:

Isolate: Put truly unavoidable wildcard actions (e.g., logs:CreateLogGroup, xray:PutTraceSegments) in their own dedicated PolicyStatement.
Suppress: Apply the suppression only to that specific statement, citing the AWS service limitation as the reason.
Scope: Ensure all other actions are scoped to specific ARNs (log streams, tables, buckets, queues, etc.).
Avoid: Do not use parent-level suppressions, as they mask future configuration drift.

Result: Required wildcards are documented and allowed, while accidental broad permissions continue to be reported.

DEV Community: Johannes Konings

CDK Mixin for Deletion Protection

Introduction

Mixin

app

Result

Conclusion

Sources and References

Aurora PostgreSQL Serverless (Express configuration) with CDK and Drizzle

Introduction

CDK Custom Resource

Aurora deployment observations

Teardown behavior

Drizzle integration

Required packages

Configuration (drizzle-kit)

Schema

Seeding script

Result

Conclusion

Sources and References

Tag log buckets created by AWS CDK for third party tools

Overview

The cdk-nag log bucket behavior

The bridge to third party tools

The extension for cdk-nag to handle log bucket tagging

The result

Sources and links

Using Server Sent Events (SSE) to sync Tanstack Db from AWS DynamoDB

Introduction

Demo Video

Architecture Overview

DynamoDB Stream and Event Table

How It Works

Implementation Links

Server Sent Events (SSE) Setup

Why SSE for Database Synchronization?

SSE Endpoint Implementation

Understanding the SSE Flow

ElectroDB Integration (Future Enhancement)

The SSE Hook

Hook Architecture

Key Features

Avoiding Infinite Loops

The Solution: Global Flag Pattern

Implementation in Collection Handlers

Using the Hook in Components

Cost Considerations

Other Options

1. WebSocket (Bidirectional)

2. Short Polling

3. GraphQL Subscriptions

4. Custom WebSocket Collection (TanStack DB)

Conclusion

Source Code

References

Use a customized CDK bootstrap template

Introduction

Create the Resources for Bootstrap via CloudFormation

KMS Key Template

S3 Log Bucket Template

The Deployment Script

Validate CloudFormation Templates with cdk-nag

Create the Customized CDK Bootstrap Template

Get the Default Template

Customize the Template

Bootstrap with the Customized Template

Conclusion

Sources and References

Simple example of TanStack DB with DynamoDB on AWS with multiple entities

Introduction

Architecture Overview

Disclaimer

Demo Video

The data model

DynamoDB single table design

Key Structure

Access Patterns

Global Secondary Indexes

ElectroDB as DynamoDB client

Configuration (`drizzle-kit`)