Supported platforms
AWS CDK Blocks supports web, desktop, and mobile platforms. Your backend API is defined once in TypeScript, and type-safe clients are available for every supported platform.
Web frameworks
CDK Blocks auto-detects your web framework and configures the development server and deployment pipeline accordingly. The following frameworks are supported:
| Framework | Minimum version | Notes |
|---|---|---|
|
Next.js |
15.x |
Full SSR support with automatic route detection and middleware handling. If your project does not install a Next.js build adapter package itself (the |
|
Nuxt |
4.x |
SSR via Nitro adapter with automatic server routes |
|
Astro |
4.x |
Static and SSR modes supported. Supported range: Astro 4 through 7. |
|
SolidStart |
1.x |
Via Nitro adapter |
|
TanStack Start |
1.x |
Via Nitro adapter |
|
SvelteKit |
2.x |
SSR via |
|
React (SPA) |
18.x |
Static single-page application, any build tool (Vite, Create React App) |
|
Vue (SPA) |
3.x |
Static single-page application via Vite |
|
Svelte (SPA) |
4.x |
Static single-page application via Vite |
|
Angular (SPA) |
17.x |
Static single-page application. Angular 17 and later write the build to a nested folder, so set |
For SPA frameworks, CDK Blocks serves static assets from CloudFront with S3 origin. For SSR frameworks (Next.js, Nuxt, Astro SSR, SvelteKit, SolidStart, TanStack Start), CDK Blocks deploys server-side rendering via Lambda compute.
Framework detection is automatic based on the dependencies, dev dependencies, and peer dependencies in your package.json. You can override it explicitly in your Hosting configuration.
Native and mobile platforms
CDK Blocks generates typed native clients from your backend API via OpenRPC codegen. You define your API once in TypeScript, and codegen produces a typed client for each native platform on top of that platform’s SDK.
| SDK | Platforms | Distribution |
|---|---|---|
|
Swift |
iOS 16 or later, macOS 13 or later |
Swift Package Manager |
|
Kotlin (Kotlin Multiplatform) |
Android (API level 23 or later), iOS, and the JVM (for example, desktop apps) |
Maven/Gradle |
|
Dart (Flutter) |
iOS, Android, web, and desktop. Dart 3.11 or later, and Flutter 3.41 or later for |
Dart packages |
How native codegen works
The build pipeline generates an OpenRPC specification (cdk-blocks/blocks.spec.json) from your ApiNamespace methods. Native codegen tools read this specification to produce typed SDKs for each platform.
The codegen pipeline has two layers:
- Platform SDK (hand-written, built once per platform)
-
Handles transport (HTTP JSON-RPC), authentication (cookie management, token injection), Realtime hydration (WebSocket connections), and FileBucket hydration (presigned URL operations).
- Generated typed facade (app-specific, produced by codegen)
-
One typed method per
ApiNamespacemethod. Calls into the platform SDK’s transport layer. Contains no transport logic.
To generate the specification:
npx blocks-generate-spec
This reads cdk-blocks/index.ts and writes cdk-blocks/blocks.spec.json. Scaffolded apps run it with npm run spec. To regenerate it on every build, add it to your build script:
{ "scripts": { "build:spec": "blocks-generate-spec", "build": "npm run build:spec && tsc && vite build" } }
Writing APIs for native compatibility
TypeScript method signatures produce correct native types automatically. For richer types (format constraints, enums), use Zod schemas:
-
Plain TypeScript types (tier 2): correct base types inferred from method signatures
-
Zod schemas (tier 1): full JSON Schema with constraints (
format: uuid,maxLength,minLength). Schema detection requires Zod 4. -
If neither is detected, parameters emit as
unknown(generatesAnyin native clients)
For best results, use explicit return types and Zod validation on complex inputs.
Hosting and deployment
CDK Blocks provides Hosting (import from aws-cdk-blocks/cdk) for deploying your frontend alongside your backend. Hosting provisions:
-
Amazon CloudFront distribution with global edge caching (the default front door; you can choose another)
-
Amazon S3 origin for static assets
-
Lambda compute for server-side rendering (SSR frameworks only)
-
Optional WAF integration for security rules
-
Custom domains with automatic DNS and TLS
-
Skew protection during rolling deployments
Hosting deploys your frontend when you run npm run deploy. A plain sandbox deploys only your backend, and npm run sandbox:preview adds Hosting in a fast preview shape. For more information, see Basic usage in the Hosting chapter.
Framework auto-detection
Hosting detects your framework from the dependencies, devDependencies, and peerDependencies in package.json. It checks in this order and uses the first match:
-
next→ Next.js adapter -
nuxt,nitropack,@solidjs/start,@tanstack/start, or one other package on Hosting’s fixed Nitro list → Nitro adapter. For any other Nitro-based framework, setframework: 'nitro' -
astro→ Astro adapter -
@sveltejs/kit→ SvelteKit adapter -
None of the above → SPA/static adapter
Override detection by setting framework explicitly in your Hosting configuration.