Skip to content

feat(cloudflare/website): Waku, Astro, SvelteKit, Nuxt resources - #1086

Merged
sam-goodwin merged 8 commits into
mainfrom
claude/frameworks-integration
Aug 4, 2026
Merged

sam-goodwin merged 8 commits into
mainfrom
claude/frameworks-integration

Conversation

@sam-goodwin

Copy link
Copy Markdown
Member

Framework website resources for Waku, Astro, SvelteKit, and Nuxt, built on a source-descriptor dispatch in the Worker provider. (Website.Nextjs is split out to #923.)

Each resource sets source: { provider: "@distilled.cloud/<fw>/source", options } on the Worker. The framework package's source module does the build (programmatic, no wrangler binary, no wrangler.json), asset manifesting, and rebuild-free input hashing for diff memoization. All four return a plain Worker<Bindings> — env takes the full binding vocabulary, url/domain/compatibility/asset routing all apply — and all four run under alchemy dev through the same dispatch (server-mode dev handle → dev proxy).

Waku

const app = yield* Cloudflare.Website.Waku("App", {
  main: "src/worker-entry.ts", // optional custom entry — can host Durable Objects
  env: { MESSAGE: "hello", COUNTER: Cloudflare.DurableObject("Counter") },
});
  • RSC SSR at request time; SSG pages prerender at build time inside workerd, served from assets
  • Zero-config defaults: nodejs_als auto-injected, assets.htmlHandling: "drop-trailing-slash" (waku links SSG pages without trailing slashes)
  • main escape hatch wraps virtual:waku/server-entry, so the deployed Worker can export DO classes alongside waku's fetch handler
  • Dev: waku's vite dev server with the rsc environment in workerd; real bindings in-process

Astro

const site = yield* Cloudflare.Website.Astro("Site", {
  env: { CACHE: kv, UPLOADS: bucket },
});
  • output: "server" by default (astro's own default is static, which would prerender "SSR" pages inside workerd where bindings don't exist); astro: { output: "static" } deploys assets-only — no server bundle at all
  • nodejs_compat auto-injected
  • Zero-config sessions: a KV namespace is auto-provisioned and bound as SESSION (sessionKVBindingName: false opts out; skipped for static output); destroyed with the stack
  • Your astro.config.* still loads natively; the resource's inline config merges over it; prerendered routes render inside workerd by default
  • Dev: astro's dev server with the ssr environment in workerd; real bindings in-process

SvelteKit

const site = yield* Cloudflare.Website.SvelteKit("Site", {
  env: { API_KEY: Alchemy.secret("API_KEY") },
});
  • In-memory kit v3 adapter (no svelte.config.js, no @sveltejs/adapter-cloudflare) + rolldown finishing pass re-bundles _worker.js for workerd
  • nodejs_compat auto-injected; bindings reach server routes via platform.env
  • Dev: kit's own vite dev server (Node SSR, full HMR); platform.env/caches/cf served by cloudflare-runtime's platform proxy with real bindings, literal env overlaid
  • Ships with a fix for kit resolving root-relative runtime ids against process.cwd() — dev now works from any working directory

Nuxt

const site = yield* Cloudflare.Website.Nuxt("Site", {
  main: "worker-entry.ts", // optional custom entry — can host Durable Objects
  nuxt: { routeRules: { "/about": { prerender: true } } },
});
  • nitro cloudflare_module preset; the only resource that natively loads your nuxt.config.ts — the nuxt prop merges over it (override wins)
  • nodejs_compat auto-injected; bindings reach handlers via event.context.cloudflare.env (+ cf, waitUntil)
  • Known limits: nitro isr route rules are ignored; custom-entry DO classes are not servable in dev (the platform proxy can't host them)
  • Dev: nitro dev in a Node worker thread; the platform reconstructed over HTTP from the cloudflare-runtime platform proxy with real bindings

Tests, examples, docs

  • Live suites test/Cloudflare/Website green: create → memoized noop → edit-redeploy → destroy per framework (also fixes the StaticSite noop plan assertion that fails on main)
  • Dev-mode {Waku,Astro,SvelteKit,Nuxt}.local.test.ts (Test.make({ dev: true })): local identity, SSR markers, env bindings, static assets
  • examples/cloudflare-website-{waku,astro,sveltekit,nuxt} with integ tests, wired into test:examples and root tsconfig references — all four verified green against the real cloud
  • Docs: rewritten frontends/astro/nuxt guides, new sveltekit + waku pages, sidebar registration

Submodule: pins cloudflare-tools to alchemy-run/cloudflare-tools#74 (framework packages, DeployTarget architecture, fixtures, and the kit runtime-id re-rooting fix).

🤖 Generated with Claude Code

BlankParticle and others added 6 commits August 4, 2026 10:31
Co-authored-by: Sam Goodwin <sam@alchemy.run>
Co-authored-by: John Royal <34844819+john-royal@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
Factor the shared shapes out of the new `Sources/*` modules and drop
redundant state added alongside them.

- `Sources/shared.ts` gains `bundleSource` (the bundle-only provider
  shape, written out verbatim in InlineScript/Prebuilt/Python/Rolldown)
  and `watchBundleDirectory` (`watchPrebuiltWorkerBundle` was a copy of
  `watchPythonWorkerBundle` modulo a path filter).
- Delete `WorkerProvider.hashViteInput`, a verbatim copy of the one in
  `Sources/Vite.ts`; both call sites go through one lazy `loadVite`.
  The copies had already drifted — carry the POSIX label normalization
  into the surviving one.
- Extract `serveBundleStream` from `LocalWorkerProvider.runWorker`;
  `runSource` re-copied ~50 lines of the same serve pipeline.
- `Rolldown.sanitizeMain` reimplemented `Bundle/TempRoot.resolveMainPath`.
- Drop the hand-rolled `nodejs_compat` merge from Astro/Nuxt/SvelteKit.
  `getCompatibility` already appends it to every non-python Worker and
  dedupes, so the blocks only fired when they shouldn't have: defeating
  an explicit `no_nodejs_compat` opt-out and the pre-2024-09-23 v2-mode
  date guard.
- Drop `DevContext.worker.name` (always `SourceContext.workerName`),
  widen `SourceBuildOutput.hash` to `Partial<SourceHash>` to match
  `hash()`, and collapse the three hash-slot comparisons in `diff`.
- `sourceModules` cached the un-memoized effect; cache the validated
  module instead. Use `createArtifactStore()` over a bare `new Map()`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Waku (live 2/2, local 2/2): API POST echo through the asset router,
middleware headers, real KV namespace via env with out-of-band
verification and destroy-side deletion; dev KV with dev: identity, HMR
with binding survival, and the Alchemy.remote() opt-out case (real
cloud namespace behind the local dev server).

Nuxt (live 2/2, local 2/2): custom worker entry hosting a Durable
Object through alchemy (Waku-pattern), POST echo, real KV via
event.context.cloudflare.env with out-of-band verification; dev KV +
HMR with binding survival, and the remote() case — ungated now that
the dev platform proxy is hosted in the sidecar runtime stack
(cloudflare-tools#99).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…egration

# Conflicts:
#	packages/alchemy/src/Cloudflare/Workers/LocalWorkerProvider.ts
#	packages/alchemy/src/Cloudflare/Workers/RuntimeBindings.ts
#	packages/alchemy/src/Cloudflare/Workers/ViteChild.shared.ts
#	packages/alchemy/src/Cloudflare/Workers/ViteChildRunner.ts
@alchemy-version-bot

alchemy-version-bot Bot commented Aug 4, 2026 •

Copy link
Copy Markdown
Contributor

Install the packages built from this commit:

alchemy

bun add alchemy@https://pkg.ing/alchemy/00acfe2

@alchemy.run/better-auth

bun add @alchemy.run/better-auth@https://pkg.ing/@alchemy.run/better-auth/00acfe2

@alchemy.run/pr-package

bun add @alchemy.run/pr-package@https://pkg.ing/@alchemy.run/pr-package/00acfe2

sam-goodwin and others added 2 commits August 4, 2026 12:04
…edirects provider fix

- WorkerProvider: fold assets _headers/_redirects into upload metadata via
  mergeAssetsConfigFiles on both the fresh-upload and keep paths — they were
  hashed into the manifest but never sent to Cloudflare
- SvelteKit: default assets.notFoundHandling from adapter.notFoundHandling so
  one prop configures both the fallback generation and the assets layer
- Astro: middleware, redirects, _headers (fresh + keep), binary responses,
  form POST, KV round-trip; local dev sessions, static-in-dev, ungated remote()
- SvelteKit: SPA fixture (app-shell fallback + server endpoints), form action
  with CSRF origin, KV round-trip; local HMR + ungated remote()
- PropSurface.test.ts: compile-time pins that Website resources reject
  script/bundle/main/source
- bun.lock: sync with package.json (@clack/prompts from main, overrides removed)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…BeDeleted

Deletion propagates in stages: getScript can briefly 404 with "This
Worker has no versions" before the 10007 not-found lands. Bump distilled
to type it on getScript (alchemy-run/distilled#414) and treat the tag as
gone in the test helper.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@sam-goodwin
sam-goodwin merged commit 7125b54 into main Aug 4, 2026
8 checks passed
@sam-goodwin
sam-goodwin deleted the claude/frameworks-integration branch August 4, 2026 19:30
filipfalcon added a commit to filipfalcon/alchemy-effect that referenced this pull request Sep 14, 2026
`props.vite` was built by a duplicated arm inside the WorkerProvider that
never consulted `ViteOptions.deriveAssets`; `makeViteSource` has existed
since alchemy-run#1086 but was only reached for `props.source`. Dispatch both through
`resolveSource`, and move the self-URL env resolution, the absolute `main`
(alchemy-run#796), and the `base` manifest prefix into the vite source.
filipfalcon added a commit to filipfalcon/alchemy-effect that referenced this pull request Sep 20, 2026
…rive asset routing from its build

Foldkit's `vite build` (`@foldkit/vite-plugin` 0.24+, `ssr.build`) emits
`dist/server/fetch.js`: a Web `fetch` handler with the built shell
embedded, its default export `{ fetch }`. That is a Worker entry, so the
Cloudflare plugin adopts it the way it adopts a TanStack Start server
bundle, and everything the resource did instead goes away: the `main` a
server-rendered app had to name, the Worker that read the shell back out
of the `ASSETS` binding, and the two asset-routing settings that failed
quietly when wrong.

The build also writes `foldkit.build.json` beside the handler, recording
which paths it prerendered, and keeps the unfilled `index.html` out of the
client output, so a server-rendered build needs no routing of its own: a
prerendered route is a file, and every other request, the front page
included, reaches the handler. A build with no manifest is client-only
and gets the single-page-application fallback, the default the other
clouds' Foldkit resources apply. Anything set in `assets` still wins.

`ViteOptions.framework: "foldkit"` names the framework whose build the
vite source knows how to read; a registry maps it to the deriver that
reads the manifest. It is plain data, so it crosses the dev-child
boundary and compares by value in props.

`props.vite` used to be built by a duplicated arm inside the
WorkerProvider that bypassed `makeViteSource`, which has existed since
alchemy-run#1086 but was only reached for `props.source`. Both now dispatch through
`resolveSource`, and the self-URL env resolution, the absolute `main`
(alchemy-run#796), and the `base` manifest prefix move into the vite source.

The SSR example drops its Worker, its `main`, and its asset settings. The
docs describe the delivery shapes and what the build derives for each.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants