Skip to content

About

Composable building blocks for full-stack AWS apps — define infrastructure and runtime code together with end-to-end type safety using TypeScript, local mocking, and native client codegen for Kotlin, Swift, and Dart.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

412 stars

Watchers

4 watching

Forks

Latest commit

 

History

986 Commits

Folders and files

AWS CDK Blocks

npm versionweekly downloadsbuild status

AWS CDK Blocks is an open-source expansion of AWS Cloud Development Kit (AWS CDK). Each CDK Block packages a construct, an interface, and the interface's AWS and local implementations. AWS best practices are built in. More than 17 Blocks cover background jobs, realtime, SQL and NoSQL databases, authentication, file storage, and AI agents. Build and test your whole app locally, then deploy the same code to your own AWS account. Every resource is CDK that you can audit and change. AWS maintains each CDK Block's best practices through versioned releases. Platform teams can package their own standards as custom CDK Blocks.

A CDK construct defines and provisions AWS infrastructure. A Block packages one application capability in three parts:

  • The infrastructure, as CDK constructs.
  • The application code that connects your app to the infrastructure.
  • A local implementation.

Select the CDK Blocks your app needs and compose them. Your app runs locally without an AWS account. When you are ready, deploy the same code to your own AWS account. The deployment provisions the AWS infrastructure, and each Block follows AWS best practices.

Platform teams can package their own standards as custom CDK Blocks and share them through npm. To create a custom CDK Block, see create-block.

Documentation: Developer Guide

Getting started

You must have Node.js 22 or later and npm 10 or later.

npm create @aws-cdk-blocks/blocks-app@latest my-app
cd my-app
npm run dev

The first command creates the app and installs its dependencies. npm run dev starts a local development server at http://localhost:3000. Each Block runs its local implementation, so you do not need an AWS account or credentials.

Define your backend in cdk-blocks/index.ts and your frontend in src/. Your frontend imports your backend and gets its types directly from the TypeScript source. You do not run a code generation step.

  • Documentation in your app: npm run docs lists the Blocks. npm run docs KVStore shows the guide for one Block. npm run help lists the tasks.
  • Templates: To start from a different template, add -- --template <name> to the npm create command. To see the templates, run npx @aws-cdk-blocks/create-blocks-app --help.
  • Existing projects: To add a cdk-blocks/ backend to an existing project, run the npm create command in the project directory. Omit the directory name, or use .. If the project is an AWS Amplify Gen 2 project, the CLI finds it and integrates with it.

For the full procedure, see the Getting started guide.

How it works

AWS CDK Blocks uses Node.js conditional exports to load different code for each context:

  • Local development: Your app runs on your machine. Each CDK Block runs its local implementation and keeps its data in memory or in local files.
  • CDK synthesis: Each CDK Block packages CDK constructs. The AWS CDK synthesizes an AWS CloudFormation template from them.
  • AWS runtime: Your app runs on AWS. Each Block calls AWS services through the AWS SDK.

For example, the line new KVStore(scope, 'todos') is a local store in development. At deployment, it becomes an Amazon DynamoDB table. In production, it makes SDK calls to that table. You do not change the code.

Blocks

Each CDK Block is an npm package. The umbrella package aws-cdk-blocks re-exports every CDK Block and the core runtime.

Category Blocks
Data and storage KVStore, Database, FileBucket
Authentication Auth (email and password, social sign-in, OIDC, and SAML in one Block)
Compute and background jobs Compute, AsyncJob, CronJob
AI Agent, KnowledgeBase
Communication Realtime, EmailClient
Configuration AppSetting, Secret
Observability Logger, Metrics, Tracer, Dashboard
Hosting Hosting

For the full catalog and the API reference of each Block, see the Developer Guide.

Supported platforms

Type safety extends from your backend to your client on these platforms:

  • Web frameworks: Next.js, Nuxt, Astro, React, Vue, Svelte, and Angular.
  • Native mobile: Swift, Kotlin, and Dart (Flutter).
  • Desktop: Kotlin, Swift, and Dart (Flutter).

Each native client has two parts. At build time, a code generator makes type-safe client code from your Blocks spec (blocks.spec.json). At run time, a library calls your backend over JSON-RPC.

  • Kotlin: Kotlin Multiplatform (Android, iOS, and JVM). A Gradle plugin and a Kotlin Multiplatform runtime.
  • Swift: A Swift package (iOS and macOS). A SwiftPM build plugin and a Foundation-based runtime.
  • Dart: Dart and Flutter. A code generator and runtime packages.

Repository layout

cdk-blocks/
├── packages/    # Blocks, the core runtime, and the create-blocks-app CLI (published to npm)
├── native/      # Native client SDKs (Kotlin, Swift, Dart)
├── test-apps/   # Example apps and end-to-end tests
├── test-infra/  # Persistent CI infrastructure (test VPCs, GitHub OIDC roles)
├── tasks/       # Agent benchmark tasks
├── docs/        # Contributor guides, design documents, and decisions
└── scripts/     # Repository tooling and automation

Building from source

You must have Node.js 22 or later.

npm install
npm run build
npm test

Contributing

To report a bug or send a pull request, see CONTRIBUTING.md. Coding agents start with AGENTS.md.

License

Apache-2.0

About

Composable building blocks for full-stack AWS apps — define infrastructure and runtime code together with end-to-end type safety using TypeScript, local mocking, and native client codegen for Kotlin, Swift, and Dart.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

412 stars

Watchers

4 watching

Forks

Releases

Packages

Used by

Contributors

Languages