Local development
Your whole app runs on your machine. When you run npm run dev, your entire application runs on your local machine: backend, frontend, database, authentication, and background jobs. You don’t need an AWS account, AWS credentials, an internet connection, or a running container daemon. The only prerequisite is Node.js version 22 or later.
Every CDK Block ships with a local implementation that exposes the same typed API as its AWS counterpart. At GA, each CDK Block runs locally on its own built-in implementation, so your app works without an AWS account. AWS Emulator support for AWS CDK Blocks is planned.
A few things need a network connection, because they call the real service:
-
An
Authprovider that signs in with a real identity provider. -
A
Databaseon an existing PostgreSQL database (DatabaseCluster.fromExisting()). -
An
Agentwhosemodel.localnames a hosted model. An Amazon Bedrock model inmodel.localalso needs AWS credentials.
This page explains how local development works, what each CDK Block maps to locally, and how to use local implementations to test your application.
How local development works
Conditional exports
Every CDK Block is an npm package with several implementations behind a single import. CDK Blocks uses Node.js conditional exportsimport statement to the right implementation for the execution context. For example, the KVStore package declares:
{ "exports": { ".": { "browser": "./dist/index.browser.js", "cdk": { "types": "./dist/index.cdk.d.ts", "default": "./dist/index.cdk.js" }, "aws-runtime": "./dist/index.aws.js", "types": "./dist/index.mock.d.ts", "default": "./dist/index.mock.js" } } }
| Context | Export condition | What resolves |
|---|---|---|
|
Local development |
|
The local implementation. Your code runs in-process on your machine, backed by the filesystem, in-memory state, or an embedded engine. |
|
Deployment (CDK synthesis) |
|
CDK Constructs that define the CDK Block’s AWS infrastructure. |
|
Production runtime (Lambda) |
|
The AWS SDK implementation that calls real AWS services. |
|
Browser |
|
The client-side code bundled into your frontend. |
The local implementation is the default resolution, so any Node.js process that imports your backend gets the local implementations automatically. This includes the dev server, your test runner, and any script you run. You don’t turn on a local mode. The local implementation is used whenever no deployment context applies. CDK Blocks applies the aws-runtime condition only when it bundles your backend for Lambda, so the AWS SDK is never loaded during local development.
You never configure this yourself. CDK Blocks sets up the build system to select the correct implementation for each context automatically.
Local implementations are for local development only. If a backend is bundled without the aws-runtime condition, it loads the local implementations instead of the AWS ones. To catch this, a CDK Block’s local implementation checks where it runs when it loads, and throws an error on compute that CDK Blocks deployed. The error starts with A Building Block mock entry (first detected: <package>) was loaded in a deployed environment. It explains how to set the aws-runtime condition. The package it names is the first CDK Block whose check ran, which can be a CDK Block that another CDK Block uses. CDK Blocks detects a deployed environment from the BLOCKS_CONFIG_BUCKET and BLOCKS_CONFIG_KEY environment variables, which it sets on every compute it provisions. On compute that CDK Blocks does not provision, the check does nothing, so the aws-runtime condition is your only protection there.
The dev server
npm run dev starts a local dev server in watch mode:
-
Your backend runs in-process. There is no separate compute to provision, and code changes reload automatically.
-
In templates with a frontend, open
http://localhost:3000. The dev server listens on that port and forwards page requests to your frontend dev server (Vite or Next.js), which runs on port 3100. -
The templates without a frontend (
backend,api-only,sql,cron, andobservability) serve only the API, on port 3001. In an Amplify project, CDK Blocks addsnpm run blocks:devinstead ofnpm run dev; it also serves the API on port 3001, andnpm run blocks:stopstops it. -
ApiNamespacecalls route through the local HTTP server with the same request and response semantics as Amazon API Gateway in production, includingBlocksContext, cookies, and headers. -
Realtimechannels connect over a WebSocket served by the dev server. -
CronJobschedules fire while the dev server is running.
The dev server listens on 127.0.0.1 only, so other machines on your network cannot reach it. This matters because it serves your whole API against local data. Anyone who can reach the port can create an account, or sign in as any user through a stubIdp() provider of an Auth Block. They can then read or change that data. To reach the dev server from a container or a remote development machine, set BLOCKS_DEV_HOST. For example, BLOCKS_DEV_HOST=0.0.0.0 npm run dev listens on every interface and prints a warning. Anyone who can reach that interface can call your API, so do this only where you control access to the port.
To stop a dev server that is running in another terminal or in the background, run npm run dev:stop. It stops the server by the process ID that npm run dev recorded in the project, so it never stops unrelated processes. If the server uses a port other than 3000, pass the port. For example, in a template without a frontend, run:
npm run dev:stop -- --port 3001
Where local state lives
CDK Blocks that persist data write to a .bb-data/ directory in the directory where you start the dev server, which is your project root. Most CDK Block instances get their own subdirectory, named after the CDK Block’s full ID: its scope ID joined to its parent scope IDs with -. For example, new KVStore(new Scope('my-app'), 'orders') writes to .bb-data/my-app-orders/. AppSetting and Secret values share one file, .bb-data/settings.json.
This has three practical benefits:
-
Data persists across restarts. Stop and restart the dev server, and your users, files, and table rows are still there.
-
You can inspect the state directly. The data is stored as plain files, so you can open your
EmailClientoutbox or a `KVStore’s contents in your editor. -
You can reset at any time. Delete
.bb-data/, or a single CDK Block’s subdirectory, to start from a clean state.
Keep .bb-data/ out of version control. Scaffolded CDK Blocks applications add it to .gitignore for you.
What each Block maps to locally
Every CDK Block exposes the same typed API locally and on AWS. The following table shows what backs that API in each environment.
| Block | Locally | On AWS |
|---|---|---|
|
|
A local user pool in |
An Amazon Cognito user pool with your configured options, or no user pool with |
|
|
File-backed store in |
DynamoDB table, with Global Secondary Indexes for its |
|
|
PGlite, an embedded WebAssembly PostgreSQL engine, running in-process with data in |
Aurora DSQL, or Aurora PostgreSQL Serverless v2 for an |
|
|
A directory in |
S3 bucket |
|
|
Typed pub/sub over a WebSocket served by the local dev server |
API Gateway WebSocket API with DynamoDB connection management |
|
|
In-process queue. Handlers execute inside the dev server, and failed jobs retry up to |
SQS queue with a dead-letter queue, consumed by the app’s default compute or by the |
|
|
In-process scheduler. |
Amazon EventBridge Scheduler schedule that invokes a Lambda function |
|
|
A canned, keyword-based provider that returns predictable responses without a real model, API key, or cloud cost. You can alternatively point an |
An Amazon Bedrock AgentCore Runtime runs the agent loop and streams over a |
|
|
A local text index built over your documents in |
Amazon Bedrock Knowledge Bases with automatic ingestion, chunking, and embedding |
|
|
Emails are captured to a local outbox ( |
Amazon SES |
|
|
Values in |
SSM Parameter Store (SecureString when |
|
|
Plaintext values in |
AWS Secrets Manager secret |
|
|
Structured logs to your terminal, using the same code path as production |
Same output, captured by CloudWatch Logs. Entries include the X-Ray trace ID when the runtime provides one. To add a request ID, use |
|
|
EMF-formatted JSON to your terminal, using the same code path as production |
Same output, captured as CloudWatch metrics |
|
|
Traces recorded to files in |
AWS X-Ray distributed tracing |
|
|
Not available locally. The dashboard route ( |
CloudWatch dashboard organized by compute, with health and logs sections, traces when the app has a |
|
|
No compute is provisioned. Every handler runs in-process in the dev server, whatever compute you assign it to |
AWS Lambda function for a |
Note two things about this table:
-
LoggerandMetricsrun the same code in both environments. Only the destination of the output differs: what you see in your terminal locally is what CloudWatch captures in production. -
The data CDK Blocks use real database engines locally.
Databaseruns actual PostgreSQL through PGlite, and on adsqlcluster it also validates your SQL against Aurora DSQL restrictions, so incompatible SQL fails on your machine instead of during a deployment.
Testing with local implementations
Local implementations also form the basis for testing. A typical CDK Blocks test setup has three levels: unit tests for your business logic, integration tests against local implementations, and end-to-end tests against a sandbox. The first two levels run entirely on your machine.
Unit test business logic with CDK Blocks as parameters
Extract business logic from your API handlers into pure functions that accept CDK Block instances as parameters. Type each parameter with only the CDK Block methods the function calls, using Pick. The function then depends only on that part of the CDK Block’s typed interface, so you can test it with a standard test runner such as Vitest, without starting the dev server:
// orders.ts - testable without the full framework import { ApiError, type KVStore } from 'aws-cdk-blocks'; export interface OrderInput { title: string; } export interface Order extends OrderInput { id: string; userId: string; } // Depend only on the KVStore methods you call, so a test can pass a small stub. export type OrderStore = Pick<KVStore<Order>, 'put'>; export async function createOrder(store: OrderStore, userId: string, input: OrderInput): Promise<Order> { if (!input.title) throw new ApiError('Title required', 400); const order: Order = { id: crypto.randomUUID(), ...input, userId }; await store.put(`${userId}:${order.id}`, order); return order; }
// orders.test.ts import { it, expect, vi } from 'vitest'; import { createOrder, type OrderStore } from './orders.js'; it('creates an order', async () => { const testStore: OrderStore = { put: vi.fn(async () => {}) }; const result = await createOrder(testStore, 'user-1', { title: 'Test' }); expect(result.title).toBe('Test'); expect(testStore.put).toHaveBeenCalledWith(`user-1:${result.id}`, result); });
The real KVStore satisfies OrderStore, so your API handler passes its store to createOrder unchanged.
For more information about structuring your application this way, see Testing in Best practices.
Integration test against local implementations
For tests that cover CDK Block behavior itself, run your application with npm run dev and test against it. CDK Blocks resolve to their local implementations automatically.
Projects created from most templates include such a test in test/e2e.test.ts. It uses the Node.js test runner (node:test) and calls your API through the same typed client as your frontend. Run it with npm run test:e2e. It uses a dev server that is already running, or starts one.
-
Tests run in milliseconds because everything is in-process.
-
Stateful CDK Blocks behave realistically: conditional writes on
KVStorefail when they should,Databaseenforces your migrations and Row Level Security, and anAsyncJobwithtrackStatus: truerecords each job’s status transitions. -
Tests run anywhere Node.js runs, including CI, without AWS credentials.
Control and inspect state through .bb-data/
Because local state is plain files, your tests can seed and assert on it directly:
-
Reset between tests or runs by deleting
.bb-data/or one CDK Block’s subdirectory. -
Assert on side effects that are hard to observe in the cloud. For example,
EmailClientwrites every email to a local outbox file. A test can trigger a password reset and then read the outbox to verify the message content.
Test against a sandbox
Local implementations match the behavior of their AWS counterparts at the API level, but some things can only be verified against real services: IAM permission boundaries, service quotas and throttling, DynamoDB query performance at scale, or real model output from Amazon Bedrock.
For those cases, deploy a sandbox with npm run sandbox and run the same tests against it. A sandbox is a fast, ephemeral deployment to AWS that each developer gets in isolation. A useful pattern is to parameterize your end-to-end tests by target environment, so the same test suite runs against localhost during development and against a sandbox URL before you ship:
| Run against | Use for |
|---|---|
|
Local dev server |
Day-to-day development, fast feedback, CI on every commit |
|
Sandbox deployment |
IAM and permission verification, performance characteristics, service-specific behavior, real AI model responses |
|
Production deployment |
Smoke tests after release |
Do most of your development and testing against local implementations, and use a sandbox when you need to verify the behavior of the AWS services themselves.
For more information about how CDK Blocks are structured, see Conditional exports. For deploying to AWS, see Deploy to AWS.