Skip to content

feat(cloudflare/website): Website.Nextjs resource - #923

Merged
sam-goodwin merged 27 commits into
mainfrom
claude/nextjs-website
Aug 4, 2026
Merged

sam-goodwin merged 27 commits into
mainfrom
claude/nextjs-website

Conversation

@john-royal

@john-royal john-royal commented Jul 22, 2026 •

Copy link
Copy Markdown
Contributor

Cloudflare.Website.Nextjs — a Cloudflare Worker deployed from a Next.js project via the wrangler-free OpenNext pipeline in @distilled.cloud/nextjs. Same coverage and support as the other framework Website resources: remote deploy, local dev, remote dev (Alchemy.remote()).

const site = yield* Cloudflare.Website.Nextjs("Site", {
  env: {
    GREETING: "Hello from Alchemy!",
    UPLOADS: bucket, // any binding, read via getCloudflareContext().env
  },
});
  • next build runs through @opennextjs/cloudflare; the worker bundles into self-contained ES modules; static assets (prerendered pages included) deploy as Workers static assets. Input files are content-hashed so unchanged projects skip the build and deploy entirely.
  • Local dev (alchemy dev) defaults to preview parity (the built OpenNext worker under workerd); nextjs: { devMode: "hmr" } runs the real next dev (Turbopack HMR) with bindings proxied onto getCloudflareContext(). Alchemy.remote() bindings resolve in both modes.

Writable ISR

New engine primitive: Cloudflare.Workers.Self — a self_service sentinel binding that lowers to a service binding targeting the Worker's own physical name on deploy (in-process self service in local dev). The Nextjs resource wires OpenNext's WORKER_SELF_REFERENCE automatically; with the KV incremental cache + DO queue config, ISR revalidation fully works:

const site = yield* Cloudflare.Website.Nextjs("Site", {
  env: {
    NEXT_INC_CACHE_KV: incCache,   // KV.Namespace
    NEXT_TAG_CACHE_KV: tagCache,   // KV.Namespace
    NEXT_CACHE_DO_QUEUE: Cloudflare.DurableObject("NEXT_CACHE_DO_QUEUE", {
      className: "DOQueueHandler", // shipped in the OpenNext bundle
    }),
  },
});

Test coverage (all against real Cloudflare)

  • Nextjs.test.ts: SSR, middleware (header + rewrite), API routes, binding read, KV round-trip, static assets, prerendered ISR, dynamic segments (generateStaticParams SSG + on-demand + catch-all), streaming SSR flush through the edge, custom not-found (unmatched + notFound()), next.config redirects/rewrites/headers, next/image (unoptimized), Pages Router page + API route, memo noop, edit→redeploy.
  • Nextjs.isr.test.ts: writable ISR — KV-cached page, on-demand revalidatePath purge, time-based regeneration through the DO queue + self-reference, and deploy-noop stability of the new binding sentinels.
  • Nextjs.local.test.ts: preview-mode local roundtrip (dev: identities, SSR/ISR/static/KV against the local simulator), hmr mode (edits served without redeploying), ungated Alchemy.remote() with out-of-band cloud verification and post-destroy gone check.
  • PropSurface.test.ts compile-time pins; examples/cloudflare-website-nextjs wired into test:examples + tsconfig (integ test deploys, asserts, destroys).

Also:

  • LocalWorkerProvider: the auto-injected ASSETS hook is no longer added for props.source workers — source providers own their asset wiring, and the hook errors in proxy-hosted dev modes with no assets directory.
  • Documented limitations (upstream): edge-runtime routes fail the build with the exact route list (silent 500s otherwise); next/image optimization needs a zone with Cloudflare Images; PPR/"use cache" and Pages-Router i18n config are out of scope for now.

The cloudflare-tools submodule points at main (alchemy-run/cloudflare-tools#82 merged).

🤖 Generated with Claude Code

john-royal and others added 17 commits July 20, 2026 13:32
…er-bundler branching

Replace the per-bundler if/else ladders in WorkerProvider
(prepareAssetsAndBundle, hasChanged) and LocalWorkerProvider
(runVite vs runWorker) with a uniform SourceProvider interface —
build() / hash() / dev() — implemented by the five existing arms:
InlineScript (props.script), Vite (props.vite), Python (.py main),
Prebuilt (bundle:false), Rolldown (default). Selection precedence,
hash slot semantics, Artifacts.cached("build") usage, the
AssetsWithHash/keepAssets fast path, and the #745 metadata hash
path are all preserved.

Also fixes local dev of prebuilt (bundle:false) workers: they were
re-bundled with rolldown in dev, violating the byte-for-byte
contract of the deploy path. PrebuiltSource.dev now fs-watches the
entry directory and re-reads the module graph instead
(watchPrebuiltWorkerBundle), and toRuntimeModules decodes
byte-content modules for workerd's string-typed module kinds.

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

Regression test for the bundle:false local-dev bug fixed by the
SourceProvider refactor: the local provider used to re-bundle
prebuilt entries with rolldown, breaking the byte-for-byte contract
(this fixture's .txt module import is not even bundleable), so local
dev of prebuilt workers failed while deploy worked.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…am submodules + research)

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

Add the serializable `source` prop to WorkerProps for external source
providers (framework integrations):

    Worker("Site", {
      source: {
        provider: "@alchemy.run/cloudflare-next",
        options: { rootDir: "." },
      },
    })

`loadSource` dynamically imports the specifier, validates the
WorkerSourceModule contract ({ make(options) }), and wraps failures in
the typed SourceProviderError naming the package to install.
`resolveSource` gives the descriptor precedence over the legacy props
and rejects `source` combined with script/vite/main. The descriptor is
hashed into the #745 metadata surface so switching providers (or
changing provider options) always triggers an update.

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

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

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

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

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…kit,nextjs}

Each example gets a bun-test integ suite mirroring cloudflare-tanstack:
deploy via Test.make (stage "test", Cloudflare state), assert the SSR page
renders the GREETING binding, a static asset serves, and destroy in afterAll
(NO_DESTROY-gated). Static-asset checks retry on body content because
Cloudflare masks the propagation window for /robots.txt with a managed
content-signals robots.txt served as 200.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Next.js needs more iteration (bundler consolidation, dependency
internalization, adapters-api migration) — moved to its own branch +
draft PR. Bumps cloudflare-tools to the matching split (build.json now
harness-owned; Framework.build() is pure).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alchemy-version-bot

alchemy-version-bot Bot commented Jul 22, 2026 •

Copy link
Copy Markdown
Contributor

Install the packages built from this commit:

alchemy

bun add alchemy@https://pkg.ing/alchemy/db19406

@alchemy.run/better-auth

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

@alchemy.run/pr-package

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

@BlankParticle
BlankParticle force-pushed the claude/frameworks-integration branch 4 times, most recently from 22f9c90 to 5a72865 Compare August 4, 2026 16:50
@sam-goodwin
sam-goodwin force-pushed the claude/frameworks-integration branch from 5a72865 to cbde484 Compare August 4, 2026 17:35
Base automatically changed from claude/frameworks-integration to feat/better-cli August 4, 2026 17:38
sam-goodwin and others added 3 commits August 4, 2026 12:51
# Conflicts:
#	bun.lock
#	cloudflare-tools
#	examples/cloudflare-website-astro/alchemy.run.ts
#	examples/cloudflare-website-astro/tsconfig.json
#	examples/cloudflare-website-sveltekit/README.md
#	examples/cloudflare-website-sveltekit/tsconfig.json
#	examples/cloudflare-website-waku/tsconfig.json
#	package.json
#	packages/alchemy/package.json
#	packages/alchemy/src/Cloudflare/Website/Astro.ts
#	packages/alchemy/src/Cloudflare/Website/SvelteKit.ts
#	packages/alchemy/src/Cloudflare/Website/Waku.ts
#	packages/alchemy/src/Cloudflare/Website/index.ts
#	packages/alchemy/src/Cloudflare/Workers/LocalWorkerProvider.ts
#	packages/alchemy/src/Cloudflare/Workers/Source.ts
#	packages/alchemy/src/Cloudflare/Workers/Sources/InlineScript.ts
#	packages/alchemy/src/Cloudflare/Workers/Sources/Prebuilt.ts
#	packages/alchemy/src/Cloudflare/Workers/Sources/Python.ts
#	packages/alchemy/src/Cloudflare/Workers/Sources/Rolldown.ts
#	packages/alchemy/src/Cloudflare/Workers/Sources/Vite.ts
#	packages/alchemy/src/Cloudflare/Workers/Worker.ts
#	packages/alchemy/src/Cloudflare/Workers/WorkerBundle.ts
#	packages/alchemy/src/Cloudflare/Workers/WorkerProvider.ts
#	packages/alchemy/src/Cloudflare/Workers/index.ts
#	packages/alchemy/test/Cloudflare/Website/Astro.test.ts
#	packages/alchemy/test/Cloudflare/Website/SvelteKit.test.ts
#	packages/alchemy/test/Cloudflare/Website/Waku.test.ts
#	packages/alchemy/test/Cloudflare/Website/fixtures/astro-app/src/pages/about.astro
#	packages/alchemy/test/Cloudflare/Workers/WorkerSource.test.ts
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…review+hmr), remote()

- Nextjs resource: devMode "server" on the source descriptor, nextjs.devMode
  ("preview" | "hmr") knob threaded to the source provider
- fixture: api/hello, api/binding (getCloudflareContext), api/kv round-trip,
  middleware (pass-through header + /mw-rewrite)
- live test: middleware, KV binding round-trip, bounded retries (the old
  exponential x15 masked failures as 10-minute hangs)
- Nextjs.local.test.ts: preview-mode roundtrip (dev: identities, SSR, ISR,
  static assets, KV), hmr-mode (real next dev, edit served without
  redeploy), ungated Alchemy.remote() with out-of-band cloud verification
- LocalWorkerProvider: don't auto-inject the ASSETS hook for props.source
  workers — sources own asset wiring; the hook errors in proxy-hosted dev
  modes with no assets directory
- PropSurface pins for Nextjs; example wired into test:examples + tsconfig

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@sam-goodwin
sam-goodwin changed the base branch from feat/better-cli to main August 4, 2026 20:33
sam-goodwin and others added 6 commits August 4, 2026 13:34
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…acts

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…Nextjs writable ISR + broad live coverage

Engine: a `self_service` sentinel binding (declared via
`Cloudflare.Workers.SelfReference` on env) lowers to a service binding
targeting the Worker's own physical name on deploy (and the parent script
on version uploads); local dev serves it with the runtime's in-process
self service.

Nextjs resource:
- always wires OpenNext's WORKER_SELF_REFERENCE (self service) — its
  absence turns ISR revalidation into a silent no-op
- Writable ISR JSDoc section: kvIncrementalCache + doQueue +
  kvNextTagCache recipe with KV/DO bindings
- documents upstream limitations: edge-runtime routes (build now fails
  with the route list, via cf-tools), next/image on workers.dev, PPR/i18n
  scope

Tests (all against real Cloudflare):
- Nextjs.isr.test.ts: KV-cached ISR, on-demand revalidatePath purge,
  time-based regeneration through the DO queue + self-reference, deploy
  noop stability of the new binding sentinels
- Nextjs.test.ts: dynamic segments (SSG + on-demand), catch-all,
  streaming SSR flush, not-found boundary (unmatched + notFound()),
  next.config redirects/rewrites/headers, next/image unoptimized,
  Pages Router page + API route
- local suite re-verified with the expanded fixture

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@sam-goodwin
sam-goodwin marked this pull request as ready for review August 4, 2026 22:40
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@sam-goodwin
sam-goodwin merged commit 80cd726 into main Aug 4, 2026
5 checks passed
@sam-goodwin
sam-goodwin deleted the claude/nextjs-website branch August 4, 2026 22:48
sam-goodwin added a commit that referenced this pull request Aug 5, 2026
The repo-wide *.js gitignore had swallowed the fixtures' entire JS
surface (middleware plus every API route) when #923 was authored, so
the checked-in apps were unbuildable. Convert both fixtures to
TypeScript (middleware.ts, route.ts, .tsx pages, checked-in tsconfigs)
so nothing is ignorable, recreate the missing API routes, and update
the test manifests. The workspace's typescript@7 (native, no JS API) is
rejected by Next's build, so a test-scoped TypeScriptCompat helper
symlinks the website package's typescript@6 into each fixture clone.

Co-authored-by: Cursor <cursoragent@cursor.com>
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