Realtime and async
This section covers AWS CDK Blocks for realtime communication and background processing.
Choosing a realtime or async Block
| Block | Best for | Avoid when |
|---|---|---|
|
|
Live updates, chat, notifications, collaborative features via WebSocket |
Your use case is request/response only (no persistent connections needed) |
|
|
Long-running background tasks, event-driven processing, queue-based workloads |
The task completes in under a few seconds (handle it synchronously) |
|
|
Scheduled recurring tasks, periodic cleanup, report generation |
You need immediate execution triggered by an event (use AsyncJob) |
Realtime
Typed WebSocket pub/sub channels. Define each namespace with a schema for type-safe message broadcasting. Any Standard Schema library works, such as Zod. Publish messages from the server and subscribe from the client. Each namespace can have multiple channels for topic-based routing.
Locally, Realtime uses an in-process EventEmitter with a local WebSocket server. On AWS, it provisions one shared API Gateway WebSocket API for the app, with a DynamoDB table for connection management. Best for live updates, chat, notifications, and collaborative features.
For more information, see bb-realtime on GitHub
AsyncJob
Background job processing. Submit work that runs asynchronously outside the request lifecycle. Define a handler function that processes each job payload. By default, jobs are fire-and-forget from the caller’s perspective, with automatic retries on failure. Set trackStatus: true to record each job’s state (queued, processing, complete, or failed) and read it with getStatus() or waitUntilComplete(). A job is failed when the handler throws on its last attempt. Status tracking adds a DynamoDB table.
Locally, AsyncJob executes handlers in-process. On AWS, it provisions an SQS queue with a Lambda consumer, or a container consumer when you assign it to a container Compute. Each job gets 3 delivery attempts (maxRetries) before it moves to a dead-letter queue that keeps messages for 14 days. The consumer receives up to 10 jobs per batch (batchSize) and waits up to 5 seconds to fill a batch (maxBatchingWindowSeconds). The queue’s visibility timeout is the 15-minute handler timeout plus the batching window, so 905 seconds by default. Best for tasks that don’t need an immediate response: sending emails, processing uploads, generating reports.
For more information, see bb-async-job on GitHub
CronJob
Scheduled task execution. Define a handler function and a cron expression or rate schedule. The handler runs automatically at the specified interval. Cron expressions use UTC unless you set timezone to an IANA time zone name, such as America/Los_Angeles. Set enabled: false to create the schedule turned off. Use input to pass the same typed payload to the handler on every run.
Locally, CronJob executes on schedule using Node.js timers. On AWS, it provisions an Amazon EventBridge Scheduler schedule that invokes a Lambda function. Best for periodic maintenance, batch processing, cleanup jobs, and report generation.
For more information, see bb-cron-job on GitHub