View a markdown version of this page

Getting started with AWS CDK Blocks - AWS CDK Blocks

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:

  • KVStore uses file-backed storage in .bb-data/ for structured data

  • Auth runs a local user pool in .bb-data/ and prints sign-up codes in the terminal instead of sending email

  • Realtime runs a local WebSocket server for pub/sub channels

  • ApiNamespace routes 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, codeDelivery prints the code in the terminal. On AWS, this provisions an Amazon Cognito user pool, which emails the code. The line export const authApi = auth.createApi(); exposes the sign-up and sign-in API that the frontend uses. Exporting the auth instance itself would expose nothing.

  • new KVStore(scope, 'todos', {…​}) creates structured data storage with a Zod schema for validation. The key option keys each todo by user and todo ID, so the API can list one user’s todos. The version field 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 named todos. 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. The todosChannel helper 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

KVStore

Key-value and structured data with indexes and queries

Auth

Email and password, social, OIDC, and SAML sign-in with sessions

ApiNamespace

Type-safe RPC from browser to backend

Database

SQL on PostgreSQL with migrations and transactions

FileBucket

File uploads and downloads

Realtime

WebSocket pub/sub channels

AsyncJob

Background job processing

Agent

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