View a markdown version of this page

Best practices for AWS CDK Blocks - AWS CDK Blocks

Best practices for AWS CDK Blocks

This topic covers best practices for structuring, securing, testing, and scaling AWS CDK Blocks applications.

Project structure

Organize your backend code for clarity and maintainability.

Keep the app definition thin. Your cdk-blocks/index.ts should contain CDK Block instantiations and API definitions. Move complex business logic into separate modules.

// cdk-blocks/index.ts - thin orchestration layer import { ApiNamespace, Scope, KVStore } from 'aws-cdk-blocks'; import { createOrder, listOrders, type Order, type OrderInput } from './orders.js'; const scope = new Scope('my-app'); const store = new KVStore<Order>(scope, 'orders', {}); export const api = new ApiNamespace(scope, 'api', (context) => ({ createOrder: (input: OrderInput) => createOrder(store, context, input), listOrders: () => listOrders(store, context), }));
// cdk-blocks/orders.ts - business logic, testable in isolation import type { BlocksContext, KVStore } from 'aws-cdk-blocks'; export interface OrderInput { title: string } export interface Order extends OrderInput { id: string; userId: string } export async function createOrder(store: KVStore<Order>, context: BlocksContext, input: OrderInput) { // validation, business rules, persistence }

Use a single Scope per application. Multiple scopes in one backend create separate resource namespaces, which adds complexity without benefit for most applications.

Co-locate related CDK Blocks. If your app has distinct domains (orders, users, notifications), group them logically but keep them in the same app definition file unless the file becomes unwieldy.

Error handling

CDK Blocks sends an error’s name and message to the frontend only for errors it knows are safe to show: an ApiError, or an error created with blocksError(). Any other error thrown in an API method, including a plain Error with a custom name, reaches the client as a nameless error with status 500 and the message Internal error. Throw an ApiError with a name to enable structured error handling on the client.

// Backend import { ApiError } from 'aws-cdk-blocks'; export const api = new ApiNamespace(scope, 'api', (context) => ({ async getItem(id: string) { const item = await store.get(id); if (!item) { throw new ApiError(`Item ${id} not found`, 404, { name: 'NotFoundError' }); } return item; }, }));
// Frontend import { api } from 'cdk-blocks'; import { isBlocksError } from 'aws-cdk-blocks/client'; try { await api.getItem('abc'); } catch (err) { if (isBlocksError(err, 'NotFoundError')) { // Handle not found } }

Best practices for errors:

  • Throw ApiError(message, status, { name }) with a descriptive name (NotFoundError, ValidationError, UnauthorizedError). Avoid a plain Error, because its name and message never reach the client.

  • For validation errors, throw ApiError(message, 400) so the client gets the message and a 400 status.

  • In frontend code, import isBlocksError from aws-cdk-blocks/client. The main aws-cdk-blocks entry exports nothing in a browser build.

  • Never expose internal details (stack traces, AWS resource ARNs) in error messages. The Error.cause property stays server-side and is never sent to the client.

  • Let unhandled errors bubble up. CDK Blocks returns them as generic 500 responses without leaking internals.

Authentication and authorization

Always validate the user in every API method that accesses user data. Don’t rely on frontend-only checks. Every ApiNamespace method is a public endpoint until it calls requireAuth. The local implementation does not check auth either, so a method you forget to gate still passes every local test.

export const api = new ApiNamespace(scope, 'api', (context) => ({ async getMyData() { // Always authenticate server-side const user = await auth.requireAuth(context); return store.get(`user:${user.userSub}`); }, }));

Scope data access by user. Use the user’s stable ID (user.userSub) as a key prefix to prevent users from accessing each other’s data. It stays the same for the user’s lifetime. Don’t key data on an email address, which a user can change.

// Good: scoped to user await store.put(`${user.userSub}:${itemId}`, data); // Bad: no user scoping - any authenticated user can access any item await store.put(itemId, data);

Make protection the default. Define namespaces that hold signed-in methods with auth.protect, so each method runs only after the session check. Gate admin methods with requireRole or the role option of auth.protect.

Choose where users live before the first deploy. The Auth Block keeps users in an Amazon Cognito user pool by default. Use store: 'builtin' when an OIDC provider is the only source of users. Changing the ID of a deployed CDK Block, or switching it from the default store to store: 'builtin', removes its user pool and every user in it.

Local development

Develop locally first. Use npm run dev as your primary development loop. Only deploy to a sandbox when you need to test behavior specific to real AWS services.

Understand local implementation limitations. Local implementations replicate the API surface but not all production behavior:

Block Local behavior Production difference

KVStore

Local filesystem store

query(), scan(), getBatch(), and index reads are eventually consistent. get() is strongly consistent by default.

Database

PGlite (embedded PostgreSQL), one statement or transaction at a time

Concurrent transactions on Aurora DSQL can fail at commit, which local runs don’t reproduce. An aurora cluster at minCapacity: 0 takes about 20 seconds to resume

Auth

Local user pool in .bb-data/. Social, SAML, and OIDC providers on the default store can’t sign in

Sessions and users are not portable between local and deployed environments. Cognito sends codes by email

Realtime

Local WebSocket server

API Gateway WebSocket has connection limits and message size limits

Clear local data when needed. Delete the .bb-data/ directory to reset all local state:

rm -rf .bb-data

Testing

Unit test your business logic independently. Extract logic from API handlers into pure functions that accept CDK Block instances as parameters.

// 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 } export async function createOrder(store: KVStore<Order>, userId: string, input: OrderInput) { 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 type { KVStore } from 'aws-cdk-blocks'; import { createOrder, type Order } from './orders.js'; it('creates an order', async () => { const mockStore = { put: vi.fn(), get: vi.fn() }; const result = await createOrder(mockStore as unknown as KVStore<Order>, 'user-1', { title: 'Test' }); expect(result.title).toBe('Test'); expect(mockStore.put).toHaveBeenCalled(); });

Integration test locally. Run your full application with npm run dev and test the API endpoints. Local implementations are deterministic and fast.

End-to-end test with sandbox. For critical paths, deploy to a sandbox and run tests against real AWS services to catch behavior differences.

Performance

Minimize CDK Block instantiations. Each CDK Block maps to AWS resources that you deploy and manage. CDK Blocks creates DynamoDB tables with on-demand billing, so an extra table costs little while idle. Each one is still another resource to deploy, monitor, and back up. Don’t create a new KVStore for every data type. Use key prefixes to partition data within a single store.

// Good: one store, partitioned by prefix const store = new KVStore(scope, 'data', {}); await store.put(`users:${id}`, userData); await store.put(`orders:${id}`, orderData); // Avoid: a separate store for each entity (more resources to deploy and manage) const userStore = new KVStore(scope, 'users', {}); const orderStore = new KVStore(scope, 'orders', {});

Declare a key for query-heavy workloads. If you need to list or sort records, or read them by other attributes, give the KVStore a schema and a key, and add indexes. A query() reads one partition, which is more efficient than a scan() of the whole table.

Keep API methods focused. By default, every ApiNamespace method in your app runs on one shared AWS Lambda function. To give a namespace more memory, pass a Compute Block in the namespace’s compute option. Avoid methods that do too many things. Split them into focused operations.

Deployment

Use sandbox for development, full deploy for production. Sandboxes use Lambda hot-swapping for speed but aren’t suitable for production traffic.

Set up separate AWS accounts for development, staging, and production. CDK Blocks deploys the same code to any account. The resources are derived from your code, not from environment-specific configuration.

Configure environment-specific settings in the CDK layer. Custom domains, VPC configuration, and other environment differences belong in cdk-blocks/index.cdk.ts, not in your runtime code.

// cdk-blocks/index.cdk.ts const isProd = process.env.DEPLOY_ENV === 'production'; const stack = await BlocksStack.create(app, stackName, { backendHandlerPath: join(__dirname, 'index.handler.ts'), backendCDKPath: join(__dirname, 'index.ts'), defaults: isProd ? BlocksPresets.production : BlocksPresets.sandbox, }); if (isProd) { // Production-only: custom domain, WAF, etc. new Hosting(stack, 'Hosting', { root: join(__dirname, '..'), api: stack, frontDoor: { features: { domain: { domainName: 'app.example.com', hostedZone: 'example.com', hostedZoneId: 'Z0123456789EXAMPLE', }, }, }, }); }

Working with coding agents

CDK Blocks gives coding agents guidance. Steering files ship with each CDK Block.

To get the best results from coding agents:

  • Keep your app definition clean and readable. Coding agents use it as context to understand your app.

  • Use descriptive CDK Block IDs. new KVStore(scope, 'user-sessions', {}) gives agents more context than new KVStore(scope, 's1', {}).

  • Write JSDoc comments on API methods. Agents use these to understand intent when generating frontend code.

  • Install CDK Block packages. Their README.md and type definitions in node_modules provide agents with API documentation and usage examples.

  • Use the Agent Block for AI capabilities. The Agent Block provides tool calling, HITL approval, and conversation persistence. Locally, it uses a canned provider for predictable testing without API keys.

Example prompt for coding agents

The following prompt shows how a coding agent can add several capabilities in one request:

Add a FileBucket for user avatars, an AsyncJob that generates thumbnails on upload, and a Realtime channel that notifies the UI when processing completes.