AWS Blocks: composable TypeScript backends with local mocking and native client codegen
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.
At a glance
- What is it?
- AWS Blocks is an AWS Labs toolkit that bundles backend code, a local emulator and CDK-generated infrastructure into a single TypeScript Block. It is aimed at teams that want DynamoDB, Cognito and Lambda wiring without writing the wiring, and it is still labelled Preview.
- Who is it for?
- Adopt AWS Blocks if you are building a new AWS backend in TypeScript and want the local development loop to work without an AWS account, or if you are shipping a Kotlin, Swift or Dart client and want generated types instead of hand-written JSON parsing. Do not adopt it if you need a stable interface for production infrastructure: the README labels the project Preview, the umbrella package sits at 0.x versions, and the repository is a labs project.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The glue code AWS Blocks removes from a full-stack TypeScript app
A typical AWS backend written by hand has three copies of the same decision. You write a DynamoDB table definition in CDK, a data access module in Lambda code, and a local stub so the frontend can run on a laptop without credentials. Change a key name and all three drift apart. AWS Blocks collapses them into one declaration. The README states that a Block is a module that gives you a complete feature: cloud resources, a runtime API, and a local implementation. The same line, `new KVStore(scope, 'todos')`, becomes a local store during development, an Amazon DynamoDB table at deploy time, and SDK calls in production, with no code changes. The audience is TypeScript developers who already accept AWS as the target and want the infrastructure derived rather than authored. It is a poor fit for someone who wants to hand-tune CloudFormation or who is not on AWS at all.
Conditional exports, CDK synthesis and the blocks.spec.json contract
The mechanism is Node.js conditional exports. The README lists three contexts: local development, where Blocks use in-memory and filesystem storage; CDK synthesis, where Blocks produce CDK constructs and AWS Blocks generates a CloudFormation template; and the AWS Lambda runtime, where Blocks call AWS services through the SDK. The same import resolves to different implementations depending on which context is loading it. That is why there is no separate infrastructure file to keep in sync, and also why the abstraction is only as good as each Block's three implementations. A second contract sits on top for mobile: the README describes native clients as build-time code generators that produce type-safe client code from a Blocks spec (`blocks.spec.json`), paired with a runtime library that calls the backend over JSON-RPC. So the spec file is the interface between your TypeScript backend and the Kotlin, Swift or Dart client, and it is generated rather than written by hand.
Installing AWS Blocks and running the dev server on port 3000
The README requires Node.js 22 or later and npm 10 or later. The scaffold command creates a project directory, installs dependencies and starts the local server. The documentation states that `npm run dev` starts a local development server at `http://localhost:3000` with every Block running a local implementation, and that no AWS account or credentials are required.
npm create @aws-blocks/blocks-app@latest my-app
cd my-app
npm install
npm run devAfter the dev server starts, the README says you define the backend in `aws-blocks/index.ts` and the frontend in `src/`, and that types flow end to end with no code generation step. Two variations matter in practice. The scaffold accepts `--template <name>`; the README lists `default`, `nextjs`, `react`, `auth-cognito`, `demo`, `bare`, `backend` and `amplify`. And running the command inside an existing project, by omitting the directory or passing `.`, adds an `aws-blocks/` backend to it. The CLI auto-detects an AWS Amplify Gen 2 project and integrates with it, which is the migration path for teams already on Amplify. If you want to build the toolkit itself rather than an app, the README gives `npm install`, `npm run build` and `npm test`, with Node.js 22 or later as the only stated requirement.
Where the Block model constrains you
The catalog is finite. The README groups Blocks into data and storage (`KVStore`, `DistributedTable`, `Database`, `DistributedDatabase`, `FileBucket`), authentication (`AuthBasic`, `AuthCognito`, `AuthOIDC`), compute and background (`AsyncJob`, `CronJob`), AI (`Agent`, `KnowledgeBase`), communication (`Realtime`, `EmailClient`), configuration (`AppSetting`), observability (`Logger`, `Metrics`, `Tracer`, `Dashboard`) and hosting (`Hosting`). If your architecture needs an AWS service outside that list, you are extending the toolkit, not configuring it. The repository layout hints at the cost: there is a `test-apps/extending-blocks-guide` workspace with its own `packages/bb-queue`, which suggests writing a Block means publishing a package with a local implementation, a CDK construct and a Lambda runtime path, not just calling an API. The second constraint is maturity. The README title carries the word Preview, and the published versions in the release list are 0.x: `@aws-blocks/pipeline@0.2.1`, `@aws-blocks/hosting@0.3.0`, `@aws-blocks/create-blocks-app@0.1.22`. Treat the Block APIs as moving. The third is that the README does not document rollback, migration between Block versions, or what happens to existing DynamoDB tables when a Block definition changes; those are the questions to ask before a production cutover.
AWS Blocks versus Amplify Gen 2
Amplify Gen 2 is the closest comparison, and the two differ in where the type boundary sits. Amplify centers on a schema-first data definition and generates GraphQL client code for web and mobile. AWS Blocks centers on imperative TypeScript constructors inside `aws-blocks/index.ts`, with no code generation step for the web side because the types are the same TypeScript types the backend exports. For native clients the two converge on codegen, but AWS Blocks generates from `blocks.spec.json` and talks JSON-RPC rather than GraphQL. The README also notes that the scaffold CLI auto-detects an Amplify Gen 2 project and integrates with it, so the relationship is partly additive rather than purely competitive. If your team already has an Amplify Gen 2 app with a working GraphQL data layer, switching buys you a different authoring model, not obviously a smaller one. If you are starting fresh and want to avoid a schema language between backend and client, the Blocks approach is the more direct one.
Maintenance, versions and what Apache-2.0 means here
The repository is not archived and the last push was on 2026-09-17, so it is current. The releases listed are all from 2026-09-08, which puts the published packages on a weekly cadence at the time of writing, but the 0.x version numbers mean semver allows breaking changes on minor bumps. Pin your Block versions and read the changesets directory in the repository before upgrading. On licensing, the project is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant; the repository also carries a NOTICE file, which Apache-2.0 expects downstream redistributions to preserve. That is the shape of the licence, not legal advice for your situation. The practical upgrade cost is the same as any infrastructure abstraction: a Block version bump can change the generated CloudFormation, so a dependency update is also an infrastructure change and should go through the same review as one.
Editorial conclusion
Adopt AWS Blocks if you are building a new AWS backend in TypeScript and want the local development loop to work without an AWS account, or if you are shipping a Kotlin, Swift or Dart client and want generated types instead of hand-written JSON parsing. Do not adopt it if you need a stable interface for production infrastructure: the README labels the project Preview, the umbrella package sits at 0.x versions, and the repository is a labs project. Before committing, verify that the Blocks you need exist in the catalog table, check that the generated client for your platform matches the JSON-RPC runtime, and read the AWS Blocks Developer Guide for the deployment and IAM story, which the README does not cover.
Frequently asked questions
What is AWS Blocks?
It is a backend toolkit for building full-stack applications on AWS, where each Block bundles application code, a local development setup and the infrastructure to run it. The README describes it as a Preview project published under the aws-devtools-labs organization.
What are Amazon blocks?
In this project a Block is a module that provides a complete feature: cloud resources, a runtime API and a local implementation. Blocks are published as npm packages, and the umbrella package @aws-blocks/blocks re-exports every Block plus the core runtime.
How do I install AWS Blocks and start a project?
Run npm create @aws-blocks/blocks-app@latest my-app, then cd my-app, npm install and npm run dev. Node.js 22 or later and npm 10 or later are required, and the dev server starts at http://localhost:3000 with local Block implementations and no AWS account.
Does AWS Blocks require an AWS account for local development?
No. The README states that npm run dev runs every Block against a local implementation using in-memory and filesystem storage, and that no AWS account or credentials are required until you deploy.
Which native platforms can AWS Blocks generate clients for?
Kotlin Multiplatform (Android, iOS, JVM), Swift (iOS, macOS) and Dart/Flutter. The README describes them as build-time code generators that produce typed clients from a Blocks spec (blocks.spec.json), paired with a runtime that calls the backend over JSON-RPC.
Is AWS Blocks open source?
Yes. The repository is published under the Apache-2.0 licence and is not archived, with the last push on 2026-09-17. The README labels the project Preview, and the published package versions are 0.x.
Community notes