View a markdown version of this page

Examples and patterns - AWS CDK Blocks

Examples and patterns

This topic shows common application patterns you can build with AWS CDK Blocks. Each example demonstrates how CDK Blocks compose together to solve real-world problems.

For complete projects you can start from, see the CDK Blocks project templates on GitHub.

CRUD API with authentication

A typical data-driven application with user authentication and scoped data access. The app stores notes in a KVStore with a key whose partition field is the user ID, so listing a user’s notes reads only that user’s items. A scan() would read every item in the table.

import { ApiNamespace, Scope, KVStore, Auth } from 'aws-cdk-blocks'; import { z } from 'zod'; const scope = new Scope('notes-app'); const auth = new Auth(scope, 'auth'); export const authApi = auth.createApi(); const notes = new KVStore(scope, 'notes', { schema: z.object({ userId: z.string(), // partition key: one partition per user id: z.string(), // sort key title: z.string(), body: z.string(), createdAt: z.number(), }), key: { partitionKey: 'userId', sortKey: 'id' }, }); export const api = new ApiNamespace(scope, 'api', (context) => ({ async create(title: string, body: string) { const user = await auth.requireAuth(context); const note = { userId: user.userSub, id: crypto.randomUUID(), title, body, createdAt: Date.now() }; await notes.put({ userId: note.userId, id: note.id }, note); return note; }, async list() { const user = await auth.requireAuth(context); // Reads only this user's partition, not the whole table return Array.fromAsync(notes.query({ where: { userId: { equals: user.userSub } } }), (entry) => entry.value); }, async delete(id: string) { const user = await auth.requireAuth(context); await notes.delete({ userId: user.userSub, id }); }, }));

CDK Blocks used: Auth, KVStore, ApiNamespace

Realtime chat

A chat application with WebSocket pub/sub and message history.

import { ApiNamespace, Scope, KVStore, Auth, Realtime } from 'aws-cdk-blocks'; import { z } from 'zod'; const scope = new Scope('chat-app'); const auth = new Auth(scope, 'auth'); export const authApi = auth.createApi(); const messageSchema = z.object({ id: z.string(), user: z.string(), text: z.string(), ts: z.number() }); // One partition per chat room; the sort key starts with the timestamp, so messages sort by time const messages = new KVStore(scope, 'messages', { schema: messageSchema.extend({ room: z.string() }), key: { partitionKey: 'room', sortKey: 'id' }, }); const realtime = new Realtime(scope, 'realtime', { namespaces: { chat: Realtime.namespace(messageSchema) }, }); export const api = new ApiNamespace(scope, 'api', (context) => ({ async sendMessage(text: string) { const user = await auth.requireAuth(context); const ts = Date.now(); const msg = { id: `${ts}-${crypto.randomUUID()}`, user: user.username, text, ts }; await messages.put({ room: 'general', id: msg.id }, msg); await realtime.publish('chat', 'general', msg); return msg; }, async getHistory() { await auth.requireAuth(context); // The 50 newest messages, read from one partition const latest = await Array.fromAsync( messages.query({ where: { room: { equals: 'general' } }, order: 'desc', limit: 50 }), (entry) => entry.value, ); return latest.reverse(); }, async subscribeChat() { await auth.requireAuth(context); // Ensure caller is authenticated return realtime.getChannel('chat', 'general'); }, }));

Frontend integration

The frontend subscribes to realtime updates:

import { api } from 'cdk-blocks'; // Subscribe to messages via API method const channel = await api.subscribeChat(); channel.subscribe((msg) => { console.log(`${msg.user}: ${msg.text}`); }); // Send a message await api.sendMessage('Hello, world!'); // Load history const history = await api.getHistory();

CDK Blocks used: Auth, KVStore, Realtime, ApiNamespace

File uploads with metadata

An application that lets users upload files from the browser and lists them with their size and upload time.

API methods take and return JSON, so do not pass file contents through them. Instead, an API method returns a file handle. The browser uses the handle to upload or download the file directly with a presigned URL. You can also return a presigned URL yourself with putUrl() or getUrl().

import { ApiNamespace, ApiError, Scope, FileBucket, Auth } from 'aws-cdk-blocks'; const scope = new Scope('files-app'); const auth = new Auth(scope, 'auth'); export const authApi = auth.createApi(); const files = new FileBucket(scope, 'uploads', { // Lets the deployed frontend upload and download with the presigned URLs corsRules: [{ allowedOrigins: ['http://localhost:3000', 'https://app.example.com'], allowedMethods: ['GET', 'PUT'], allowedHeaders: ['Content-Type'], }], }); export const api = new ApiNamespace(scope, 'api', (context) => ({ async startUpload(name: string, contentType: string) { const user = await auth.requireAuth(context); // The browser sends the file straight to storage with this handle return files.createUploadHandle(`${user.userSub}/${name}`, { contentType }); }, async listFiles() { const user = await auth.requireAuth(context); const results = []; for await (const file of files.scan({ prefix: `${user.userSub}/` })) { results.push({ key: file.path, size: file.size, lastModified: file.lastModified.toISOString() }); } return results; }, async download(key: string) { const user = await auth.requireAuth(context); if (!key.startsWith(`${user.userSub}/`)) { throw new ApiError('Forbidden', 403, { name: 'ForbiddenError' }); } return files.getFileHandle(key); }, }));

The frontend uploads and downloads with the handles:

import { api } from 'cdk-blocks'; // Upload: the file goes from the browser to storage, not through your API const upload = await api.startUpload(file.name, file.type); await upload.upload(file); // Download const [first] = await api.listFiles(); const download = await api.download(first.key); const blob = await download.download();

A deployed bucket has no cross-origin resource sharing (CORS) rules by default, and it does not inherit the stack’s allowed origins. Without corsRules that list your frontend origin, browser uploads work locally but fail after you deploy. A rule that combines a wildcard origin (*) with PUT, POST, or DELETE fails synthesis.

CDK Blocks used: Auth, FileBucket, ApiNamespace

SQL-backed application

An application using relational data with joins and transactions. The cdk-blocks/migrations/db/ folder, named after the CDK Block ID, holds numbered .sql files that create the tables. They run once each, before the first query locally and during the deploy in AWS. For a complete project, see the sql template.

import { ApiNamespace, Scope, Database, Auth, sql } from 'aws-cdk-blocks'; const scope = new Scope('store-app'); const auth = new Auth(scope, 'auth'); export const authApi = auth.createApi(); // Runs the numbered .sql files in cdk-blocks/migrations/db/ once each, in order. // The directory is named after the Block ID and is relative to the project root. const db = new Database(scope, 'db'); interface Order { id: number; user_id: string; status: string; created_at: string; } export const api = new ApiNamespace(scope, 'api', (context) => ({ async createOrder(items: Array<{ productId: string; qty: number }>) { const user = await auth.requireAuth(context); return db.transaction(async (trx) => { const [order] = await trx.query<Order>(sql` INSERT INTO orders (user_id, status) VALUES (${user.userSub}, 'pending') RETURNING * `); for (const item of items) { await trx.execute(sql` INSERT INTO order_items (order_id, product_id, quantity) VALUES (${order.id}, ${item.productId}, ${item.qty}) `); } return order; }); }, async getOrders() { const user = await auth.requireAuth(context); return db.query<Order>(sql` SELECT * FROM orders WHERE user_id = ${user.userSub} ORDER BY created_at DESC `); }, }));

The migration creates both tables:

-- cdk-blocks/migrations/db/001_create_orders.sql CREATE TABLE orders ( id BIGINT GENERATED BY DEFAULT AS IDENTITY (CACHE 65536) PRIMARY KEY, user_id TEXT NOT NULL, status TEXT NOT NULL, created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE order_items ( order_id BIGINT NOT NULL REFERENCES orders (id), product_id TEXT NOT NULL, quantity INTEGER NOT NULL ); CREATE INDEX ASYNC orders_user_id ON orders (user_id);

CDK Blocks used: Auth, Database, ApiNamespace

Common patterns

Pattern Approach

User-scoped data

Use user.userSub as the partition key (or key prefix) to isolate data per user

Optimistic UI

Return the created/updated object from API methods so the frontend can update immediately

Background work

Use AsyncJob for queued work and CronJob for scheduled work

Multi-tenant

Use Scope IDs or key prefixes to partition data by tenant

Feature flags

Store flags in an AppSetting and read them in API methods before executing logic

Related resources

For runnable projects: