sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ aws/ frontend/ websites.mdx

Alchemy deploys frontends to AWS with a family of AWS.Website resources. Each one builds your project programmatically and deploys it as a serverless site — the SSR server on a Lambda Web Function, static assets in a private S3 bucket, and a CloudFront distribution whose edge router serves uploaded files from S3 and forwards everything else to the server — with no AWS-specific configuration: no CDK, no CloudFormation, no adapter setup. Your framework's own config file (astro.config.*, nuxt.config.ts, vite.config.ts, ...) loads natively; Alchemy layers its AWS integration on top.

  • Vite — any client-only Vite project (React, Vue, Solid, or a plain SPA): assets-only, no Lambda; your vite.config.* loads natively.
  • Foldkit — Foldkit SPA, SSR, and prerendered apps.
  • Astro — Astro sites, server-rendered or fully static; your astro.config.* loads natively.
  • Nextjs — Next.js apps on Next's own standalone server, with ISR and image optimization through a shared S3 cache; your next.config.* is honored as-is.
  • Vinext — vinext (Next.js API on Vite) apps on a streaming Lambda; your vite.config.ts loads natively.
  • Nuxt — Nuxt apps built through nitro's node preset; your nuxt.config.ts loads natively.
  • ReactRouter — React Router v8 in framework mode, built through your own vite build.
  • SvelteKit — SvelteKit apps with a wrangler-free in-memory AWS adapter; your vite.config.ts loads natively.
  • TanStackStart — TanStack Start (React or Solid), built through your own vite build.
  • Waku — Waku (React Server Components) apps.
  • Octane — OctaneJS fullstack apps built through your own vite build with the AWS marker adapter.
  • StaticSite — any directory of files, optionally produced by a build command, for static generators like Zola and Hugo or pre-built SPAs.
  • Router — a shared CloudFront front door: one distribution serving several sites (or a site plus an API), routed at the edge.

Every resource shares the same surface: domain (ACM certificate + Route 53 records, or records on another DNS host), server configuration (timeout, env, maxConcurrencyPerEnvironment, maxEnvironments), assets, edge customizations, and invalidation. All builds are memoized by content-hashing the input files — an unchanged project skips the build and deploy entirely. Under alchemy dev, every resource runs the framework's own dev server (native HMR) instead of deploying; Alchemy.remote() opts back into the full live deployment.

Serve from several Regions

List extra Regions to run the server in each of them behind one global domain. CloudFront forwards to it, and each request reaches the nearest Region:

const site = yield* AWS.Website.Nuxt("Website", {
  regions: ["us-east-1", "eu-west-1"],
});

The site's URL doesn't change when you add or remove Regions. Nextjs and Vinext keep their data caches in the home Region, so a server in another Region reaches back to it for cached pages; regions helps most for sites without a server-side cache.

Choose the server

The SSR server runs on a Lambda Web Function: your framework's own Node server, serving many requests per environment and streaming each response. Web Functions run in a subset of Regions. Elsewhere, set server: "function" to run the server on a Lambda Function behind a streaming Function URL:

const site = yield* AWS.Website.Nuxt("Website", {
  server: "function",
  memorySize: 2048,
});

memorySize, architecture, and runtime apply only to server: "function"; a Web Function has a fixed 2 GB, Arm64 and Node.js 24.

What's supported

FrameworkResourceGuide
React / Vite SPAViteReact SPA
VueViteVue
FoldkitFoldkitFoldkit
TanStack Start (React & Solid)TanStackStartTanStack Start
React RouterReactRouterReact Router
AstroAstroAstro
Next.jsNextjsNext.js
vinextVinextvinext
NuxtNuxtNuxt
SvelteKitSvelteKitSvelteKit
WakuWakuWaku
OctaneJS (fullstack)OctaneOctane
Zola, Hugo, or any static generatorStaticSiteStatic sites

Every row is backed by a checked-in example or a live deploy test in the Alchemy repository. The last row is deliberately open-ended: StaticSite deploys any directory of files (running your build command first if you give it one), so any generator works the same way.

How to choose

Use the resource named after your framework. Astro, Nextjs, Nuxt, ReactRouter, SvelteKit, TanStackStart, Waku, and Octane each drive their framework's own build and know its output layout, config surface, and dev server.

Use Vite when the app is client-only and a single vite build produces the whole thing — a React or Vue SPA, or any Vite project with no server. It creates no Lambda.

Use StaticSite when the output is plain files from an arbitrary build command that emits a directory (Zola, Hugo, or any other generator without a dedicated resource).

Use Router when several sites (or a site plus an API) should share one CloudFront distribution and one domain — distributions take minutes to create, and each custom domain can only attach to one.

Where next