@alchemy.run/frontend-frameworks/waku
Wrangler-free Waku integration. Implements
@alchemy.run/frontend-frameworks/core's Framework service — programmatic
build / dev over waku's public unstable_ API — with no wrangler
dependency and no wrangler.json/toml read or written, and with the deploy
platform decoupled behind a deploy target passed as a value. Cloudflare
Workers is the built-in (and default) target, shipped at
@alchemy.run/frontend-frameworks/waku/cloudflare.
Architecture: framework half × deploy-target half
The package separates two concerns (see
packages/frontend-frameworks/src/core/README.md → "Architecture: frameworks × deploy
targets" for the full doctrine):
| Module | Role | Platform imports |
|---|---|---|
. (src/waku/index.ts, src/waku/Waku.ts) | Framework half: waku config synthesis, programmatic build/dev orchestration, BuildOutput collection, deploy-target resolution | None (enforced by a unit test) |
./cloudflare (src/waku/cloudflare.ts) | Cloudflare target: WakuTarget implementation — injects @alchemy.run/cloudflare-runtime/vite, selects the ./adapter fork | cloudflare-vite-plugin |
./adapter (src/waku/adapter.ts) | Wrangler-free fork of waku/adapters/cloudflare; bundled into the worker by waku's vite pipeline | worker-side only |
./source (src/waku/source.ts) | Alchemy Cloudflare.Worker source provider ({ provider: "@alchemy.run/frontend-frameworks/waku/source" }) wrapping the framework with the cloudflare target | cloudflare-runtime (types) |
A future platform (e.g. AWS Lambda) is a new target module implementing the
same WakuTarget hooks — zero changes to the framework half or to
framework-core.
The WakuTarget contract
WakuTarget extends framework-core's generic DeployTarget (opaque
config, bundle conditions/externals, optional wholesale build,
finish, serve) with the two hooks waku's toolchain needs:
interface WakuTarget<Config = unknown> extends DeployTarget<Config> {
/** Absolute path of the adapter module selected via `unstable_adapter`. */
adapter(context: WakuTargetContext): Effect<string, DeployTargetError>;
/** Vite plugins injected FIRST inside waku's `vite.plugins` (dev + build). */
vitePlugins(context: WakuTargetContext): Effect<PluginOption[], DeployTargetError>;
}
// WakuTargetContext = { root, wakuDirectory, phase: "build" | "dev" } Why exactly these two seams:
adapteris mandatory. Ifunstable_adapteris left unset (and noCLOUDFLARE/WORKERS_CIenv var is set), waku silently selectswaku/adapters/node, which cannot run on a non-Node runtime — every request 500s opaquely. The framework half always pins the target's adapter.vitePluginsinjection position is load-bearing. The target's plugins go inside waku'sconfig.vite.plugins(waku'sextraPluginsplaces them first, ahead of waku's own environments plugin) — the position upstream documents for@cloudflare/vite-plugin, and the only one where the target's request-proxy middleware registers before waku's Node request bridge (which assumes a runnable Node environment and breaks against a workerd-backed one).
The cloudflare target (@alchemy.run/frontend-frameworks/waku/cloudflare)
Default export: (config?: CloudflareVitePluginOptions) => WakuTarget — the
factory shape resolveDeployTarget expects from a target module. It:
- resolves
adapterto this package's./adapterfork — a ~200-line fork ofwaku/adapters/cloudflare(built entirely on publicwaku/adapter-builders+waku/internalsexports) whose single functional change isbuildEnhancers: [], droppingwaku/adapters/cloudflare-build-enhancer— the sole wrangler-file writer in waku (it scrapes/writeswrangler.jsonc,dist/server/wrangler.json,.wrangler/deploy/config.json). Everything else (Hono app,cloudflare:workersenv access, SSG via the preview server) is behavior-identical to upstream. - produces
@alchemy.run/cloudflare-runtime/vitewithmainpinned to waku's rsc worker entry (waku/dist/lib/vite-entries/entry.server.js, resolved from the project's waku install — the deep path is not in waku's exports map) and theviteEnvironments: { entry: "rsc", children: ["ssr"] }topology. Pinningmainis mandatory: waku's rsc environment declares two rolldown inputs (index+build) while the plugin asserts exactly one entry. - declares
bundle: { conditions: ["workerd", "worker", "module", "browser"], external: ["cloudflare:"] }.
The target's config is the cloudflare vite plugin's options: worker
name/bindings/assets behavior, compatibilityDate / compatibilityFlags
(defaulted to include nodejs_als — required by waku core — unless the
user's flags already provide AsyncLocalStorage via nodejs_als,
nodejs_compat, or nodejs_compat_v2; full nodejs_compat only if user
dependencies need it), and (from the alchemy source provider) the in-memory
dev worker wiring. main and viteEnvironments are pinned and cannot be
overridden.
How build works
Replicates waku's runBuild with zero CLI involvement:
- Load the project's
vite,waku/internals,waku/vite-plugins(loadProjectModule— the project's installed copies are the ones driven, never ours). - Resolve the deploy target, run its hooks, and synthesize waku's
Configin memory (unstable_resolveConfig): the target's adapter asunstable_adapter, the target's plugins first invite.plugins,waku/honodeduped (so the adapter fork — which lives outside the project — resolves the project's copies), the documented rsc/ssroptimizeDeps.includeentries, andplatform: "neutral". vite.createBuilder({ configFile: false, plugins: [unstable_combinedPlugins(config), collectorPlugin] }).buildApp(), withprocess.env.NODE_ENVset first (waku's environmentsPlugin bakes it intodefine) andglobalThis.__WAKU_START_PREVIEW_SERVER__set — the SSG step ofbuildAppcallsunstable_startPreviewServer, which throws without it. The preview server resolves the same waku config as the build (upstream parity: waku's CLI reuses the loaded config's plugin instances for bothcreateBuilderandvite.preview), so the cloudflare target'sconfigurePreviewServerhook serves the freshly built worker through workerd and SSG renders inside workerd with real bindings — a top-levelimport { env } from "cloudflare:workers"in a page module is fine. Waku's adapter registers its Node fallback middleware behind the proxy; it only fires for targets without a preview mode.- Collect the
BuildOutputwith framework-core's collector, using a post-buildAppdisk re-read: waku writes__waku_build_metadata.jsand prunes static-only server chunks after the bundler'swriteBundle(in-memory captures alone are non-bootable — the worker imports the metadata module). Entry selection is pinned to waku'sserver/index.js(the adapter'sExportedHandler), because the rsc environment emits multiple entry chunks (index,build, and any wrapped worker entry) and last-entry-wins picking is nondeterministic. - Apply the target's
finishpass, if it defines one (the cloudflare target does not), and return theBuildOutputin-memory only — persistence (dist/build.json) is the e2e harness's concern.
If the target defines a wholesale build hook, the framework delegates the
entire production build to it instead (the OpenNext-style takeover; no waku
orchestration runs).
How dev works
Replicates waku's runDev: vite.createServer({ configFile: false, plugins: [unstable_combinedPlugins(config)] }) with the target's plugins inside
waku's config. With the cloudflare target, the rsc environment runs in
workerd (module-runner) with in-memory bindings and HMR; waku's own Node
request bridge middleware never fires because the workerd proxy middleware
registers ahead of it. A port passed to dev() is strict; the
options-level port is a non-strict default.
Options
import wakuFramework, { make } from "@alchemy.run/frontend-frameworks/waku";
make({
/** Deploy target: value | (config) => target | module specifier |
* harness carriage. Default: "@alchemy.run/frontend-frameworks/waku/cloudflare",
* loaded from the PROJECT's node_modules. */
target: cloudflareTarget({ compatibilityDate: "2026-03-10" }),
/** @deprecated — the pre-target alias for the target's config
* (the harness's top-level `vite` field). */
vite: undefined,
/** Extra waku config merged into the in-memory resolveConfig input
* (srcDir, distDir, basePath, vite, ...). */
waku: { srcDir: "src" },
/** Project root (default: process.cwd()). */
root: undefined,
/** Non-strict default dev port. */
port: 3101,
}); Target forms accepted by target (resolved per operation with
framework-core's resolveDeployTarget):
a target value — full type safety over the config; build it yourself:
import cloudflareTarget from "@alchemy.run/frontend-frameworks/waku/cloudflare"; make({ target: cloudflareTarget({ compatibilityDate: "2026-03-10", worker: { name: "app" } }) });a factory
(config) => WakuTarget— applied to the carried config;a module specifier string — loaded from the project's
node_modules; the module default-exports (or namestarget) a value or factory;the e2e harness carriage
{ name?, cloudflare?: { worker } }— the shape the harness's options spread hands the framework factory; selects the default target module withtarget.cloudflare.worker ?? viteas its config.
Usage (e2e harness)
// e2e.config.ts
import * as Options from "@alchemy.run/cloudflare-test-tools/e2e/Options";
export default Options.make({
framework: "@alchemy.run/frontend-frameworks/waku",
target: {
cloudflare: {
worker: {
compatibilityDate: "2026-03-10",
compatibilityFlags: ["nodejs_als"],
worker: { name: "my-waku-app", bindings: [] },
},
preview: {
/* miniflare options for `e2e preview` / Playwright "live" */
},
},
},
}); Or the typed factory form for waku-specific options:
import wakuFramework from "@alchemy.run/frontend-frameworks/waku";
framework: (options) => wakuFramework({ ...options, port: 3101, waku: { srcDir: "app" } }), The deprecated top-level vite / miniflare fields keep working as aliases
for target.cloudflare.worker / target.cloudflare.preview.
SSG runs inside workerd
The SSG step of buildApp boots a vite.preview server over the same
resolved config as the build, and the cloudflare vite plugin's
configurePreviewServer hook serves the freshly built worker through
workerd (cloudflare-runtime's Runtime.start over the built server
modules + the client assets directory). Consequences:
- A top-level
import { env } from "cloudflare:workers"in a page module works — waku prerenders every static page through the worker, not the Node process, so thecloudflare:scheme resolves natively. (In a build without a platform vite plugin, upstream renders SSG through the adapter's Node fallback middleware and the same import breaks withERR_UNSUPPORTED_ESM_URL_SCHEME.) - Static pages that read Cloudflare bindings at build time render with them — the preview worker is configured from the target's plugin options (bindings, compatibility date/flags, assets), so the emitted HTML bakes in real binding values.
This matches what upstream's @cloudflare/vite-plugin provides via its own
configurePreviewServer (miniflare over the built output).
Limitations
- Durable Objects cannot be defined in a waku app (upstream limitation) — use service bindings to a separate worker.
- Waku assumes
process.cwd()is the project root in places (html-shell input, relative rolldown inputs). The alchemy source provider compensates by running build/dev under a cwd lock; the e2e harness runs from the fixture directory anyway. nodejs_alsis required (AsyncLocalStorage); waku core needs nothing more from nodejs_compat. The cloudflare target defaultscompatibilityFlagsto includenodejs_alswhen the user's flags provide no ALS (nodejs_als,nodejs_compat, ornodejs_compat_v2).
Version pinning
Everything this package touches in waku is unstable_-prefixed
(unstable_combinedPlugins, unstable_resolveConfig,
unstable_createServerEntryAdapter, unstable_startPreviewServer, the
adapter system itself) and waku is in beta — waku is pinned exactly
(1.0.0-rc.4). Treat version bumps as deliberate migrations: re-verify
the adapter fork against upstream's packages/waku/src/adapters/cloudflare.ts,
the two-input rsc environment merge, and the preview-server global.