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

import PackageManagers from "../../../../components/PackageManagers.astro";
export const devDeps = "@alchemy.run/frontend-frameworks";

AWS.Website.Waku deploys a Waku app (React Server Components) to AWS. It builds the project programmatically: the RSC server runs on a Lambda Web Function and streams its responses, and the client output — including SSG-prerendered pages — is served from a private S3 bucket through CloudFront. No waku.config.ts edits are required — if you have one it loads natively — and there is no adapter to configure and no build command to run.

Install

The build integration is not bundled with alchemy. Install @alchemy.run/frontend-frameworks; the resource loads its /waku and /waku/node exports from your project at deploy time. It is only used at build time, so a dev dependency is enough:

Configure Waku

No framework config is required — a fresh Waku project deploys as-is. If your project has a waku.config.ts, Alchemy loads it natively (exactly as Waku's own CLI does) and uses it as the base config — including Vite plugins under its vite field:

// waku.config.ts
import { defineConfig } from "waku/config";
import tsconfigPaths from "vite-tsconfig-paths";

export default defineConfig({
  basePath: "/",
  vite: {
    plugins: [tsconfigPaths()],
  },
});

waku.config.* is the home for static configuration. For deploy-time values — anything that varies by stage — the waku prop merges overrides over the file, per key:

export const Website = AWS.Website.Waku("Website", {
  waku: {
    basePath: "/docs/",
  },
});

The one key Alchemy owns is unstable_adapter — setting it fails the build with an actionable error.

:::note Vite configuration must live in waku.config.ts's vite field — a standalone vite.config.ts is not loaded, same as Waku's own CLI. :::

Declare the Website

Declare the site as a module-level const (rather than inline in the Stack):

// alchemy.run.ts
import * as AWS from "@alchemy.run/aws";

export const Website = AWS.Website.Waku("Website");

Add it to the Stack

Yield the site from your Stack and return its URL:

// alchemy.run.ts
import * as Alchemy from "alchemy";
import * as Effect from "effect/Effect";

export default Alchemy.Stack(
  "MyWakuSite",
  {
    providers: AWS.providers(),
    state: AWS.state(),
  },
  Effect.gen(function* () {
    const site = yield* Website;
    return { url: site.url };
  }),
);

Pages rendered as "static" are generated at build time, uploaded to S3, and served from the edge; dynamic pages and API routes stream from the server.

See examples/aws-website-waku for the checked-in example.

Add environment variables

The server function's environment is configured under env — plain values, or outputs from other resources in the Stack:

// alchemy.run.ts
export const Website = AWS.Website.Waku("Website", {
+  env: {
+    GREETING: "Hello from alchemy",
+    API_BASE: api.url,
+  },
});

The values are set on the server at deploy time and injected into the dev server's process environment under alchemy dev, so server code reads the same values in both modes.

Read the environment in server code

Server components and API routes read the environment through waku's getEnv — on AWS it is backed by the server's process.env at request time, and it keeps page modules portable across deploy targets:

// src/pages/index.tsx
import { getEnv } from "waku";

export default async function HomePage() {
  const greeting = getEnv("GREETING") ?? "hello";
  return <h1>{greeting}</h1>;
}

export const getConfig = async () => ({ render: "dynamic" }) as const;

Run on a Lambda Function

Web Functions run in a subset of Regions. Elsewhere, set server: "function": the app builds with the /waku/aws deploy target and runs on a Lambda Function behind a streaming Function URL, tuned with memorySize, architecture, and runtime:

// alchemy.run.ts
export const Website = AWS.Website.Waku("Website", {
+  server: "function",
+  memorySize: 2048,
});

Local dev

bun alchemy dev

alchemy dev runs Waku's own dev server (native HMR) instead of deploying; site.url is the local address and no AWS resources are created. Wrap the site in Alchemy.remote() to deploy the real infrastructure even during dev.

Custom domain

const site = yield* AWS.Website.Waku("Web", {
  domain: { name: "app.example.com" },
});

The hosted zone is inferred from the hostname. Pass hostedZoneId to pin it when several zones could match.