View a markdown version of this page

Supported platforms - AWS CDK Blocks

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 nextjs template does), Hosting uses a pinned one. The pinned adapter supports Next.js 15.5.18 or a later 15.x release, and Next.js 16.2.6 or later.

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 @sveltejs/adapter-node. If your svelte.config.js sets no adapter, Hosting adds adapter-node for the build. Any other adapter fails synthesis.

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 buildOutputDir (for example, dist/my-app/browser).

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 blocks_runtime_flutter

Dart packages blocks_runtime, blocks_codegen, and blocks_runtime_flutter

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 ApiNamespace method. 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 (generates Any in 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, set framework: '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.