Getting started with AWS CDK Blocks
In this tutorial, you set up your development environment, create a todo application with user authentication, data persistence, and a type-safe API. The application runs locally and can optionally deploy to AWS.
Prerequisites
To develop with AWS CDK Blocks, you need the following on your local machine:
-
Node.js version 22 or later. Download from https://nodejs.org/.
-
npm version 10 or later (included with Node.js).
-
A code editor with TypeScript support, such as Visual Studio Code or Kiro.
To verify your Node.js and npm versions:
node --version npm --version
For the optional deployment step, you also need:
-
AWS CLI configured with credentials
-
AWS CDK bootstrapped in your account
For deployment details, see Deploy your application to AWS.
Create your CDK Blocks project
Create a new CDK Blocks application:
npm create @aws-cdk-blocks/blocks-app@latest my-todo-app cd my-todo-app
The command copies the default template into my-todo-app and installs its dependencies. The project has the following structure:
my-todo-app/ ├── .cdk-blocks/ │ └── config.json ├── cdk-blocks/ │ ├── index.ts │ ├── index.cdk.ts │ ├── index.handler.ts │ ├── client.js │ ├── package.json │ └── tsconfig.json ├── public/ │ └── favicon.svg ├── src/ │ └── index.ts ├── test/ │ └── e2e.test.ts ├── .gitignore ├── AGENTS.md ├── README.md ├── cdk.json ├── index.html ├── package.json ├── tsconfig.app.json ├── tsconfig.json ├── tsconfig.node.json └── vite.config.ts
Run the application locally
Start the development server:
npm run dev
In your web browser, navigate to http://localhost:3000. You see a todo application with authentication, CRUD operations, priorities, and sorting.
All CDK Blocks are running with local implementations:
-
KVStoreuses file-backed storage in.bb-data/for structured data -
Authruns a local user pool in.bb-data/and prints sign-up codes in the terminal instead of sending email -
Realtimeruns a local WebSocket server for pub/sub channels -
ApiNamespaceroutes calls through a local HTTP server
No AWS account is needed. Changes to your code are reflected immediately through hot reload.
Explore the backend code
The cdk-blocks/index.ts file defines your backend and API in a single place. The listings in this section show its code without the template’s comments. The first part creates the CDK Blocks:
import { ApiNamespace, ApiError, Scope, Auth, KVStore, Realtime } from 'aws-cdk-blocks'; import { z } from 'zod'; const scope = new Scope('my-app'); const auth = new Auth(scope, 'auth', { users: { signInWith: ['email'], caseSensitive: false }, codeDelivery: async (username, code, purpose) => { console.log(`[auth] ${purpose} code for ${username}: ${code}`); }, }); export const authApi = auth.createApi(); const todoSchema = z.object({ userSub: z.string(), todoId: z.string(), title: z.string(), completed: z.boolean(), priority: z.number(), // 1=high, 2=medium, 3=low version: z.number(), createdAt: z.number(), }); const todos = new KVStore(scope, 'todos', { schema: todoSchema, key: { partitionKey: 'userSub', sortKey: 'todoId' }, }); const rt = new Realtime(scope, 'live', { namespaces: { todos: Realtime.namespace(z.object({ action: z.enum(['created', 'updated', 'deleted']), todoId: z.string(), })), }, }); const todosChannel = (userSub: string) => encodeURIComponent(userSub);
This code creates three CDK Blocks:
-
new Auth(scope, 'auth', {…})creates email and password sign-in, where users sign in with their email address. Sign-up confirms the address with a 6-digit code. Locally,codeDeliveryprints the code in the terminal. On AWS, this provisions an Amazon Cognito user pool, which emails the code. The lineexport const authApi = auth.createApi();exposes the sign-up and sign-in API that the frontend uses. Exporting theauthinstance itself would expose nothing. -
new KVStore(scope, 'todos', {…})creates structured data storage with a Zod schema for validation. Thekeyoption keys each todo by user and todo ID, so the API can list one user’s todos. Theversionfield supports optimistic locking. Locally, this is a file-backed store in the.bb-data/directory. On AWS, this provisions a DynamoDB table. -
new Realtime(scope, 'live', {…})creates a pub/sub namespace namedtodos. The API publishes an event to it whenever a todo changes, so your other open tabs reload their lists. Each user has their own channel. ThetodosChannelhelper encodes the user ID, so a user ID can’t add/segments that place one user’s channel under another’s. Locally, this runs a WebSocket server inside the development server. On AWS, this provisions an Amazon API Gateway WebSocket API and a DynamoDB table for connections.
The API methods use these CDK Blocks. This listing is shortened. The template also defines updatePriority and deleteTodo.
export const api = new ApiNamespace(scope, 'api', (context) => ({ async subscribeTodos() { const user = await auth.requireAuth(context); return rt.getChannel('todos', todosChannel(user.userSub)); }, async createTodo(title: string, priority: number = 2) { const user = await auth.requireAuth(context); const todoId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`; const todo = { userSub: user.userSub, todoId, title, completed: false, priority, version: 1, createdAt: Date.now(), }; await todos.put({ userSub: user.userSub, todoId }, todo); await rt.publish('todos', todosChannel(user.userSub), { action: 'created' as const, todoId }); return todo; }, async listTodos(sortBy?: 'priority' | 'title') { const user = await auth.requireAuth(context); const list = await Array.fromAsync( todos.query({ where: { userSub: { equals: user.userSub } } }), (entry) => entry.value, ); if (sortBy === 'priority') return list.sort((a, b) => a.priority - b.priority); if (sortBy === 'title') return list.sort((a, b) => a.title.localeCompare(b.title)); return list; }, async toggleTodo(todoId: string) { const user = await auth.requireAuth(context); const todo = await todos.get({ userSub: user.userSub, todoId }); if (!todo) throw new ApiError('Todo not found', 404, { name: 'TodoNotFoundException' }); await todos.put( { userSub: user.userSub, todoId }, { ...todo, completed: !todo.completed, version: todo.version + 1 }, { ifFieldEquals: { version: todo.version } }, ); await rt.publish('todos', todosChannel(user.userSub), { action: 'updated' as const, todoId }); return { success: true }; }, // updatePriority and deleteTodo follow the same pattern. }));
Every method starts with auth.requireAuth(context). Each ApiNamespace method is a public endpoint until it calls requireAuth, and the local implementation does not warn you if you forget. The toggleTodo method throws an ApiError with status 404 so the client gets a named error, and it uses ifFieldEquals to reject a write if another request changed the todo first.
The template keys each user’s data on user.userSub, which stays the same for the user’s lifetime. Key your own data on it too.
Explore the frontend code
The frontend in src/index.ts imports the backend API directly:
import { api, authApi } from 'cdk-blocks';
There is no client generation step, no API URL configuration, and no SDK initialization. TypeScript provides full type safety. If you change a method signature in the backend, the frontend shows a compile error immediately.
Make a change
Add a method that deletes all completed todos. In cdk-blocks/index.ts, add it inside the ApiNamespace definition, after deleteTodo:
async clearCompleted() { const user = await auth.requireAuth(context); const list = await Array.fromAsync( todos.query({ where: { userSub: { equals: user.userSub } } }), (entry) => entry.value, ); const done = list.filter((todo) => todo.completed); for (const todo of done) { await todos.delete({ userSub: user.userSub, todoId: todo.todoId }); await rt.publish('todos', todosChannel(user.userSub), { action: 'deleted' as const, todoId: todo.todoId }); } return { cleared: done.length }; },
The development server hot-reloads. You can immediately call the new method from the frontend with full type safety:
const { cleared } = await api.clearCompleted();
Available CDK Blocks
The following table lists the CDK Blocks used in this tutorial and other commonly used CDK Blocks:
| Block | Purpose |
|---|---|
|
|
Key-value and structured data with indexes and queries |
|
|
Email and password, social, OIDC, and SAML sign-in with sessions |
|
|
Type-safe RPC from browser to backend |
|
|
SQL on PostgreSQL with migrations and transactions |
|
|
File uploads and downloads |
|
|
WebSocket pub/sub channels |
|
|
Background job processing |
|
|
AI agent with tool calling |
For the complete list of all available CDK Blocks, see CDK Blocks reference.
Optional: Deploy your application to AWS
When you’re ready to deploy to a real AWS environment, see Deploy your application to AWS for the full setup and deployment steps.
Clean up
To stop the local development server, press Ctrl+C in your terminal.
If you deployed to AWS and want to remove all resources:
# Remove production deployment npm run destroy # Remove sandbox environment npm run sandbox:destroy
Next steps
-
AWS CDK Blocks concepts: Learn about CDK Blocks, scopes, the app definition, and how code maps to resources.
-
CDK Blocks reference: Explore all available CDK Blocks and their APIs.
-
Examples and patterns: See common application patterns and sample code.