Skip to content

Waku

Neon.Website.Waku builds Waku’s React Server Components handler and static pages into a Node 24 Fetch artifact for a Neon Function. It reuses the Node build target, but the deployed entry does not open a listening socket. No container or S3 website is created.

Prepare the app

Section titled “Prepare the app”

Use an existing Waku app or the runnable Waku example. Keep the React/RSC peer versions compatible with your Waku version. Configure deployment credentials, then install in the app directory:

Install Alchemy and its matching Effect dependencies first; use Node 24 for this build toolchain.

Terminal window
pnpm add -D @alchemy.run/frontend-frameworks @vercel/nft

Keep waku.config.*, but do not set unstable_adapter: the integration selects Waku’s Node adapter. The waku resource prop accepts srcDir, distDir, and basePath overrides.

Define the stack

Section titled “Define the stack”
alchemy.run.ts
import * as Alchemy from "alchemy";
import * as Neon from "alchemy/Neon";
import * as Effect from "effect/Effect";


export default Alchemy.Stack(
  "NeonWaku",
  { providers: Neon.providers(), state: Alchemy.localState() },
  Effect.gen(function* () {
    const site = yield* Neon.Website.Waku("Web", {
      rootDir: ".",
    });
    return { url: site.url };
  }),
);

The Fetch wrapper serves built files and resolves extensionless HTML paths before falling through to Waku’s handler. Dynamic rendering and RSC requests use that handler. Server code can read private env values from process.env; never pass service credentials through client-component props or public build variables.

Develop and deploy

Section titled “Develop and deploy”
Terminal window
pnpm exec alchemy dev
pnpm exec alchemy deploy
pnpm exec alchemy destroy

Run separately, destroying when finished. Dev runs Waku’s native development server and HMR, returns a local URL, and creates no implicit Project or Function. Append .pipe(Alchemy.remote()) to the Website Effect to use live deployment during dev.

Without scope, live deploy creates an Ohio Project. Pass either project or branch for an existing backend; choose Ohio when adding storage. See scope and credentials.

Reference

Section titled “Reference”