AWS Blocks in practice: what one full build showed me
A full app built on the AWS Blocks preview: what works, the five places where the preview pushed back, what a short backend file deploys, and appropriate use cases.
AWS Blocks is ready for prototypes, internal tools, and learning projects. It is not yet ready for a product that carries revenue, unless you pin every version and read the source of each Block you depend on.
I reached that view by building one complete app on the public preview: Quiz Night, a live multiplayer quiz. The app uses ten Blocks, from hosting to an agent. It ran on my machine with no AWS account, and the same code deployed to production. Local development is the strongest part of the framework. The preview also has gaps between its guide and its packages, and three of them changed my design. This article covers both.
What AWS Blocks is
AWS Blocks is an open-source TypeScript framework for application backends. AWS released it as a public preview on June 16, 2026. It has no charge of its own. You pay for the AWS services that your app uses.
A Block is an npm package that gives you one backend capability: a key-value store, authentication, a queue-backed job, a WebSocket channel. Each Block holds three things behind one import:
| Where the code runs | What the import gives you |
|---|---|
| Your machine | A local implementation that uses files, memory, or an embedded engine |
| Deployment | Cloud Development Kit constructs that define the AWS resources |
| AWS Lambda | Calls to the real AWS services |
Node.js conditional exports select the correct one. You do not turn on a local mode. The line new KVStore(scope, 'todos') is a file-backed store on your machine and a DynamoDB table on AWS, and your code does not change between the two.
A Blocks app is also a Cloud Development Kit app. You can add any construct beside the Blocks, and you can change the resources that a Block creates. This matters later in this article.
The test app
I chose an app that gives every Block real work. In Quiz Night, a host signs in and creates a game on a topic. An agent writes the questions, and the host approves them. Players join on their phones with a six-character code. Each round lasts 20 seconds, and questions, results, and the leaderboard reach every screen as they happen.
| Block | Job in Quiz Night | AWS service behind it |
|---|---|---|
Hosting | Serves the Next.js frontend on a custom domain | CloudFront, S3, Lambda |
ApiNamespace | 13 typed backend methods | API Gateway, Lambda |
AuthCognito | Host accounts | Cognito |
KVStore | All game records in one store | DynamoDB |
AsyncJob | Question generation, which takes several seconds | Simple Queue Service, Lambda |
CronJob | A daily question, and cleanup of old games | EventBridge, Lambda |
Agent | Writes the questions through a tool call | Bedrock |
Realtime | Live messages to hosts and players | API Gateway WebSocket, DynamoDB |
Metrics and Logger | 11 custom metrics and structured logs | CloudWatch |
Dashboard | A dashboard built from the metric definitions | CloudWatch |
The versions were AWS Blocks 0.9.0 with Next.js 16, React 19, Tailwind CSS 4, and Zod 4. Each Block has its own version number. For example, KVStore was 0.4.0 and Agent was 0.7.0. I pinned every package to an exact version.
I wrote a full spec first, then built the app with Claude Code against that spec. The spec was written from the developer guide. That detail matters, because some findings below are places where the guide did not match, or did not cover, what the packages do.
One file defines the backend
The backend entry point is aws-blocks/index.ts. It creates the Blocks and lists the methods. AWS Blocks reads the same file to derive the infrastructure. The sketch below shows the shape. It is cut down from the real file.
// aws-blocks/index.ts (simplified)
import {
ApiNamespace,
AuthCognito,
KVStore,
Realtime,
Scope,
} from "@aws-blocks/blocks";
import { gameMessageSchema } from "./shared/messages.js";
import { joinGame } from "./domain/players.js";
import { startRound } from "./domain/rounds.js";
const scope = new Scope("quiz-night");
const store = new KVStore(scope, "quiz-data", {});
const auth = new AuthCognito(scope, "auth", { signInWith: "email" });
const realtime = new Realtime(scope, "realtime", {
namespaces: { game: Realtime.namespace(gameMessageSchema) },
});
// deps wraps the Blocks as small interfaces: store, publisher, clock, metrics.
export const api = new ApiNamespace(scope, "api", (context) => ({
joinGame: (code: string, nickname: string) => joinGame(deps, code, nickname),
async startRound(code: string) {
const host = await auth.requireAuth(context);
return startRound(deps, host, code);
},
}));
The frontend imports api and calls a method as a typed function:
import { api } from "aws-blocks";
const { playerId, token } = await api.joinGame(code, nickname);
There is no route table and no client generation step. A change to a method’s return type shows up in the frontend as a compile error. A thrown error keeps its name across the call, so the browser can tell a ConflictError from a RoundClosedError and show the correct text.
I kept this file thin. The logic lives in plain functions that receive the Blocks as parameters. That one decision made the tests fast, as the next section shows.
What worked
The whole app runs on one machine. npm run dev starts the frontend, the backend, sign-in, the WebSocket server, the queue, and the scheduled jobs. No AWS account is needed. A full game runs in three browser tabs before any AWS resource exists.
Local state is plain files. Each Block writes to its own folder in .bb-data/. You can open a record in an editor, and you can delete a folder to reset one Block.
Local Blocks fail the same way the cloud ones do. A conditional write on the local KVStore fails when the key exists, as DynamoDB does. So I tested race conditions on my machine: two players who join with one nickname at the same instant, and a host who closes a round twice. Both tests run in Jest with no server.
Tests need no emulator. The test harness creates real local Blocks in a temporary folder and passes them to the domain functions. The suite covers a complete three-player game, a failed question generation, and the cleanup job. It needs no AWS credentials, so it also runs in the deployment pipeline.
Sign-in works offline. AuthCognito simulates a user pool locally, including the verification code step. On AWS it creates a real Cognito user pool.
The sandbox closes the gap. npm run sandbox deploys the backend to AWS and serves the frontend from your machine. It is the place to check what the local versions cannot show, such as Cognito email delivery and real model output, before the full deployment.
The dashboard needs no layout work. Dashboard builds a CloudWatch dashboard from the metric definitions. The deployed app redirects /aws-blocks/dashboard to it.
Where the preview pushed back
Five properties of the preview changed the design or the process. None of them stopped the project. Most of them showed up in a package or on AWS, and not in the guide.
| Finding | Effect | What I did |
|---|---|---|
KVStore 0.4.0 has no prefix listing | The planned key design could not list the records of one game | Index records, updated with compare-and-swap |
A failed AsyncJob waits 900 seconds on AWS before its retry | A host would wait 15 minutes for a second attempt | The handler counts attempts and submits the job again |
| The local agent provider does not behave like a model | It makes one tool call per turn and ignores the topic | The server assigns the round, and the job sends turns until all rounds are full |
| A queued job can read an out-of-date record on AWS | The job would stop, because the game was not yet in the expected state | The job gives itself back to the queue |
The Blocks Pipeline construct renames resources | It cannot take over a stack that exists | A plain pipeline that runs npm run deploy |
The key-value store has four operations
The developer guide says that KVStore supports listing by prefix. Version 0.4.0 has get, put, delete, and scan. My spec read every player of a game with a prefix such as player:{code}:, so the data model had to change.
The replacement is one index record per collection. For example, players:{code} holds every player of a game, and each update is a compare-and-swap: read the record, change it, and write it only if nobody else wrote first. This has one benefit. A join checks the nickname and the 30-player limit in a single atomic write. It also has one cost. Many players who join at the same instant compete for one record. The join method tries up to 40 times with random waits.
KVStore also supports automatic expiry. The daily answer records use it, so the cleanup job does not need to find them.
Retries on AWS are slow by default
Locally, AsyncJob runs the handler in-process, and a retry is immediate. On AWS, a handler that throws waits 900 seconds before the next attempt.
The handler now treats a failed generation as a normal result. It records the attempt in the game record and submits a new job. On the third failed attempt it marks the game as failed and tells the host. The Block’s own retry remains as protection against a crash.
The local agent is a stand-in
Locally, the Agent Block uses a canned provider. It calls no model. In this project it made one tool call per turn, always for round 1, and it wrote sample questions that ignore the topic. This is correct for a pipeline test, but code that works with it can still fail with a real model, and the reverse.
Two changes made the code work with both. The tool that saves a question assigns the lowest open round if the requested round is taken. The job sends turns until every round is full or a turn makes no progress. For real output on a local machine, the Agent Block can use a model served by Ollama.
On AWS, the agent needs Amazon Bedrock model access in the account, and the Bedrock console can ask for a one-time use case form first. Without it, each job fails with ModelUnavailableException.
A queued job can run ahead of its record
The method that creates a game writes the game record and then submits the job. On AWS, the job can start and read a game record that is out of date. The first version of the job stopped in that case, because the game was not in the expected state. The job now gives itself back to the queue and tries again. Local tests cannot show this class of fault. The sandbox can.
Block identifiers are permanent
Each Block has an identifier, such as quiz-data. For a Block that holds data, a changed identifier means a new resource, and the old data is lost. I chose all twelve identifiers before the first deployment and treated them as frozen.
What the code deploys
The backend file is short, and the stack is not. One synthesis of the app gave a single CloudFormation stack with about 200 resources.
| Resource | Count |
|---|---|
| Lambda functions | 20 |
| DynamoDB tables | 6 |
| Simple Queue Service queues | 4 |
| EventBridge schedules | 2 |
| Cognito user pool | 1 |
| CloudFront distribution | 1 |
| Bedrock AgentCore runtime | 1 |
| CloudWatch dashboard | 1 |
I declared one key-value store and one queued job. The other tables and queues belong to Blocks that need their own storage, such as Realtime for its connections. Read the synthesized template before the first deployment. You are the owner of every resource in it, and of its cost.
The synthesis also gave warnings that are easy to miss. API Gateway access logging is off by default. The alarm topic that Hosting creates has no subscriber until you add one, so its alarms notify nobody.
Deployment
npm run deploy deploys the backend and the frontend. It prints the deployment target first, and it ends with one line that holds the two addresses. A first deployment can take more than 10 minutes.
The custom domain was the easy part. Hosting takes a domain name and a Route 53 hosted zone. It then creates the certificate, one record that validates it, and the two alias records for the site. CloudFront needs the certificate in us-east-1, so I deployed the whole stack there.
The pipeline was the hard part. AWS Blocks has a Pipeline construct, and this project could not use it. It is built on Cloud Development Kit Pipelines, which puts the app inside a stage. Inside a stage, the Cloud Development Kit gives different logical identifiers to some resources. In this app, the two queue event source mappings and 15 Lambda permissions got new identifiers.
My production stack already existed. CloudFormation would treat the new identifiers as new resources and try to create a second event source mapping for the same queue and function. Lambda refuses that, and the deployment would fail.
The fix was to leave the construct out. The pipeline is a plain CodePipeline with one CodeBuild project. The build runs lint, the type check, and the Jest tests, and then runs the same npm run deploy that I run by hand. A failed check stops the build before production changes.
The order matters. If you want the Blocks Pipeline construct, adopt it before the first production deployment. After that deployment, the stack’s logical identifiers are fixed.
Removal leaves data. npm run destroy removes the stack. The production preset keeps the data tables and the user pool, which is the correct default. You must delete them by hand when a project ends.
Who should use it now
Use AWS Blocks now if these are true:
- You are building a prototype, an internal tool, or a learning project.
- Your team writes TypeScript and can read a Cloud Development Kit template. You will need to.
- You want tests that run against real behavior with no AWS account.
Wait for general availability if these are true:
- The app holds data that you cannot lose, and you are not prepared to read each Block’s source.
- You need interfaces that stay the same between releases. Each Block is still at a version below 1.0.
If you start today, these seven rules would have saved me the most time:
- Pin every package to an exact version.
- Read the readme of each Block package before you design around it. The guide can be ahead of the package, or behind it.
- Pick the data Block by its access pattern.
KVStoreis for records that you get by a known key. Use a different Block if you need queries. - Choose the Block identifiers before the first deployment, and do not change them.
- Decide how the pipeline deploys before the first production deployment.
- Run the sandbox early. Retry timing, permissions, and model output only show up on AWS.
- Before you share the address, set a budget alert and limit who can sign up. An agent behind open sign-up lets strangers spend your money.
The idea behind AWS Blocks is sound: one line of code that is a local store on your machine and a managed table on AWS. The preview already delivers that for a complete app. What it still lacks is agreement between the guide and the packages, and defaults that suit an interactive app, such as the retry delay.
Sources
- AWS announces AWS Blocks (Preview), June 16, 2026: release date, price, Regions
- What is AWS Blocks?: the Block list and how conditional exports work
- AWS Blocks concepts: Scope,
ApiNamespace, Block identifiers - Local development: what each Block maps to locally
- Data storage: the
KVStoredescription - AWS Blocks on GitHub: package source and readme files
- The Quiz Night spec, implementation plan, and runbook: versions, design changes, resource counts, and the pipeline