vinext 1.0.0-beta.8 → 1.0.0

package/README.md

@@ -4,6 +4,8 @@ Run Next.js applications on Vite, with Cloudflare Workers as the primary deploym
 
 **Website:** [vinext.dev](https://vinext.dev)
 
+**Documentation:** [vinext.dev/docs](https://vinext.dev/docs)
+
 > **Read the announcement:** [How we rebuilt Next.js with AI in one week](https://blog.cloudflare.com/vinext/)
 
 > **Under active development.** vinext supports substantial Next.js applications today, but it is not yet a drop-in replacement for every application or production workload. Expect compatibility gaps, especially in newer App Router features, and evaluate it against your own application before adopting it.
@@ -28,7 +30,7 @@ These are active compatibility areas, not permanent exclusions:
 - **Cache Components and Partial Prerendering:** `"use cache"` is partially implemented, but full `cacheComponents` behavior is still incomplete. Cache profiles, tags, partial shells, resume behavior, prefetching, and some dev/build cache semantics do not yet match Next.js in every case.
 - **Build-time image and font optimization:** images can be optimized at request time on Cloudflare, but vinext does not yet reproduce Next.js's complete build-time image pipeline. Google Fonts are loaded from the CDN, and local font CSS is injected at runtime rather than extracted during the build.
 - **Native modules in App Router development:** packages such as `sharp`, `resvg`, `satori`, `lightningcss`, and `@napi-rs/canvas` can fail in Vite's RSC development environment. Production builds support more of these cases than development mode.
-- **Platform-specific and advanced Next.js behavior:** `runtime` and `preferredRegion` route config are currently ignored, and some recently introduced or undocumented Next.js behavior may not yet be reproduced.
+- **Platform-specific and advanced Next.js behavior:** `preferredRegion` route config is ignored, and `runtime` doesn't choose where a route runs (outside `cacheComponents`, a `runtime = "edge"` App Router page is never ISR-cached, as in Next.js), and some recently introduced or undocumented Next.js behavior may not yet be reproduced.
 
 Run `vinext check` against an existing application before migrating. If a gap is not listed here, check the [open issues](https://github.com/cloudflare/vinext/issues) or file a focused reproduction.
 
@@ -78,28 +80,39 @@ npm install react-server-dom-webpack
 npm install -D @vitejs/plugin-rsc
 ```
 
-Replace `next` with `vinext` in your scripts:
+Add a Vite config:
+
+```ts
+import { defineConfig } from "vite";
+import vinext from "vinext";
+
+export default defineConfig({
+  plugins: [vinext()],
+});
+```
+
+Then use Vite for development and builds:
 
 ```json
 {
   "scripts": {
-    "dev": "vinext dev",
-    "build": "vinext build",
+    "dev": "vite dev",
+    "build": "vite build",
     "start": "vinext start"
   }
 }
 ```
 
 ```bash
-vinext dev          # Development server with HMR
-vinext build        # Production build
+npx vite dev        # Development server with HMR
+npx vite build      # Production build
 npx @vinext/cloudflare deploy  # Build and deploy to Cloudflare Workers
 ```
 
 With Vite+, use `vpx @vinext/cloudflare deploy`, or
 `vp exec vinext-cloudflare deploy` when running the locally installed bin.
 
-vinext auto-detects your `app/` or `pages/` directory, loads `next.config.js`, and configures Vite automatically. No `vite.config.ts` required for basic usage.
+The `vinext()` plugin auto-detects your `app/` or `pages/` directory and loads `next.config.js`.
 
 Your existing `pages/`, `app/`, `next.config.js`, and `public/` directories work as-is. Run `vinext check` first to scan for known compatibility issues, or use `vinext init` to [automate the full migration](#migrating-an-existing-nextjs-project).
 
@@ -107,8 +120,8 @@ Your existing `pages/`, `app/`, `next.config.js`, and `public/` directories work
 
 | Command                            | Description                                                             |
 | ---------------------------------- | ----------------------------------------------------------------------- |
-| `vinext dev`                       | Start dev server with HMR                                               |
-| `vinext build`                     | Production build (multi-environment for App Router: RSC + SSR + client) |
+| `vite dev`                         | Start dev server with HMR                                               |
+| `vite build`                       | Production build (multi-environment for App Router: RSC + SSR + client) |
 | `vinext start`                     | Start local production server for testing                               |
 | `npx @vinext/cloudflare deploy`    | Build and deploy to Cloudflare Workers                                  |
 | `vp exec vinext-cloudflare deploy` | Build and deploy to Cloudflare Workers with Vite+                       |
@@ -116,16 +129,26 @@ Your existing `pages/`, `app/`, `next.config.js`, and `public/` directories work
 | `vinext check`                     | Scan your Next.js app for compatibility issues before migrating         |
 | `vinext lint`                      | Delegate to eslint or oxlint                                            |
 
-Options: `-p / --port <port>`, `-H / --hostname <host>`, `--turbopack` (accepted, no-op).
+`vinext dev` and `vinext build` remain as thin aliases for the project-local Vite commands.
+They require a Vite config; if one is missing, run `vinext init`. Vite owns their options,
+output, and exit behavior. For older configured projects, the aliases still preload dotenv
+before Vite evaluates the config and add `"type": "module"` (renaming known CommonJS config
+files to `.cjs`) when an unambiguous default Vite config requires the ESM migration. An explicit
+`"type": "commonjs"` is never changed. Direct `vite dev` and `vite build` do not perform these
+wrapper compatibility steps.
 
-`@vinext/cloudflare deploy` options: `--preview`, `--env <name>`, `--name <name>`, `--skip-build`, `--dry-run`, `--experimental-tpr`.
+`@vinext/cloudflare deploy` options: `--preview`, `--env <name>`, `--name <name>`, `--skip-build`, `--dry-run`, `--warm-cache`, `--traffic-aware-warm-cache`.
 
 `vinext init` prompts for a deployment target, defaulting to Cloudflare. Agents must ask the
 user which target they want, then pass `--platform=cloudflare` or `--platform=node`.
 
 Other options: `--port <port>` (default: 3001), `--skip-check`, `--force`.
 
-If your `next.config.*` sets `output: "standalone"`, `vinext build` emits a self-hosting bundle at `dist/standalone/`. Start it with:
+Cloudflare init uses `cf` and `cloudflare.config.ts` by default. Both `vinext init`
+and `create-vinext-app` accept `--legacy-wrangler-cloudflare-init` to retain the
+legacy Wrangler setup. Existing Wrangler configs are not automatically migrated.
+
+If your `next.config.*` sets `output: "standalone"`, `vite build` emits a self-hosting bundle at `dist/standalone/`. Start it with:
 
 ```bash
 node dist/standalone/server.js
@@ -164,7 +187,7 @@ This will:
 5. Add `dev:vinext`, `build:vinext`, and `start:vinext` scripts to `package.json`
 6. Prompt for a deployment platform (Cloudflare by default, or Node)
 7. Generate the matching `vite.config.ts`
-8. For Cloudflare, generate `wrangler.jsonc`
+8. For Cloudflare, generate `cloudflare.config.ts` for `cf` and Cloudflare Vite plugin v2
 
 The migration is non-destructive -- your existing Next.js setup continues to work alongside vinext. It does not modify `next.config`, `tsconfig.json`, or any source files, and it does not remove Next.js dependencies.
 
@@ -251,34 +274,24 @@ vinext has native integration with Cloudflare Workers through `@cloudflare/vite-
 
 #### Prerequisites
 
-Before running `npx @vinext/cloudflare deploy` for the first time you need to authenticate with Cloudflare and tell wrangler which account to deploy to.
+Before running `npx @vinext/cloudflare deploy` for the first time, run `vinext init --platform=cloudflare` to install `cf` and Cloudflare Vite plugin v2, create or update `vite.config.*`, and generate `cloudflare.config.ts`.
 
 **Authentication — pick one:**
 
-- **`wrangler login`** (recommended for local development) — opens a browser window to authenticate. Run it once and wrangler caches the token.
+- **`cf auth login`** (recommended for local development) — opens a browser window to authenticate.
 - **`CLOUDFLARE_API_TOKEN` env var** (CI / non-interactive) — create a token at [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens) using the **Edit Cloudflare Workers** template. That template grants all the permissions `@vinext/cloudflare deploy` needs.
 
 **Account ID:**
 
-wrangler needs to know which Cloudflare account to deploy to. Add your account ID to `wrangler.jsonc`:
-
-```jsonc
-{
-  "account_id": "<your-account-id>",
-  ...
-}
-```
-
-Find your account ID in the Cloudflare dashboard URL (`dash.cloudflare.com/<account-id>`) or by running `wrangler whoami` after logging in.
+Set `accountId` at the top level of `defineConfig` in `cloudflare.config.ts`, outside `worker`. Find your account ID in the Cloudflare dashboard URL (`dash.cloudflare.com/<account-id>`).
 
 Alternatively, set the `CLOUDFLARE_ACCOUNT_ID` environment variable instead of hardcoding it in the config file.
 
-Run `vinext init --platform=cloudflare` first to install dependencies and create or AST-update
-`vite.config.*` and `wrangler.jsonc`. `@vinext/cloudflare deploy` then validates that setup, builds the
-application, and deploys to Workers without rewriting project configuration.
+`@vinext/cloudflare deploy` validates the initialized setup, builds the application,
+and deploys its Cloudflare Build Output with `cf` without rewriting project configuration.
 
 Cloudflare init can also configure image optimization declaratively in the Vite config with
-`imagesOptimizer()` and add the matching Wrangler Images binding. The built-in fetch handlers register
+`imagesOptimizer()` and add the matching Images binding to `cloudflare.config.ts`. The built-in fetch handlers register
 that optimizer at runtime; image optimization is not implemented or generated by `@vinext/cloudflare deploy`.
 
 ```bash
@@ -288,7 +301,17 @@ npx @vinext/cloudflare deploy --env staging
 vp exec vinext-cloudflare deploy --env staging
 ```
 
-Use `--env <name>` to target `wrangler.jsonc` `env.<name>`. `--preview` is shorthand for `--env preview`.
+Use `--env <name>` to select the Vite mode for the build and deployment. `--preview` is shorthand for `--env preview`.
+
+In Response Store service-binding mode, both Workers build together, but the cache Worker is deployed explicitly. After creating the R2 bucket named by init, run:
+
+```sh
+pnpm run build:vinext
+pnpm run deploy:response-store
+pnpm run deploy:vinext
+```
+
+For `create-vinext-app` projects, use `build` and `deploy` instead of `build:vinext` and `deploy:vinext`. Redeploy the Response Store only when its package or config changes; normal application deployments do not deploy auxiliary Workers.
 
 The init command also auto-detects and fixes common migration issues:
 
@@ -315,35 +338,42 @@ export default async function Page() {
 
 This works because `@cloudflare/vite-plugin` runs the RSC environment in workerd, where `cloudflare:workers` is a native module. In production builds, the import is externalized so workerd resolves it at runtime. All binding types are supported: D1, R2, KV, Durable Objects, AI, Queues, Vectorize, Browser Rendering, etc.
 
-Define your bindings in `wrangler.jsonc` as usual:
+Add bindings to your Worker's `env` in `cloudflare.config.ts`:
 
-```jsonc
-{
-  "name": "my-app",
-  "compatibility_date": "2026-02-12",
-  "compatibility_flags": ["nodejs_compat"],
-  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "..." }],
-  "kv_namespaces": [{ "binding": "CACHE", "id": "..." }],
-}
+```ts
+import { bindings } from "cf/config";
+
+env: {
+  // ...existing bindings
+  DB: bindings.d1({ name: "my-db" }),
+  CACHE: bindings.kv(),
+},
 ```
 
-For TypeScript types, generate them with `wrangler types` and the `env` import will be fully typed.
+Binding and runtime types are generated in `.cloudflare/types` during dev and build. Include that directory in `tsconfig.json`; run `cf workers types` before standalone type-checks. Generated types and Build Output stay gitignored.
 
 > **Note:** You do not need `getPlatformProxy()`, a custom worker entry with `fetch(request, env)`, or any other workaround. `cloudflare:workers` is the recommended way to access bindings in vinext.
 
-#### Traffic-aware Pre-Rendering (experimental)
+#### Traffic-aware pre-warming
 
-TPR queries Cloudflare zone analytics at deploy time to find which pages actually get traffic, pre-renders only those, and uploads them to KV cache. The result is SSG-level latency for popular pages without pre-rendering your entire site.
+Traffic-aware warming queries Cloudflare zone analytics at deploy time to select the routes that actually get traffic. Those routes then go through vinext's standard staged CDN pre-warming flow, including route resolution, cacheability checks, and promotion.
 
 ```bash
-npx @vinext/cloudflare deploy --experimental-tpr                    # Pre-render pages covering 90% of traffic
-vp exec vinext-cloudflare deploy --experimental-tpr                 # Same, with Vite+
-npx @vinext/cloudflare deploy --experimental-tpr --tpr-coverage 95  # More aggressive coverage
-npx @vinext/cloudflare deploy --experimental-tpr --tpr-limit 500    # Cap at 500 pages
-npx @vinext/cloudflare deploy --experimental-tpr --tpr-window 48    # Use 48h of analytics
+npx @vinext/cloudflare deploy --traffic-aware-warm-cache                              # Pre-warm routes covering 90% of traffic
+vp exec vinext-cloudflare deploy --traffic-aware-warm-cache                           # Same, with Vite+
+npx @vinext/cloudflare deploy --traffic-aware-warm-cache --traffic-aware-coverage 95  # More aggressive coverage
+npx @vinext/cloudflare deploy --traffic-aware-warm-cache --traffic-aware-limit 500    # Cap at 500 routes
+npx @vinext/cloudflare deploy --traffic-aware-warm-cache --traffic-aware-window 48    # Use 48h of analytics
+npx @vinext/cloudflare deploy --traffic-aware-warm-cache --warm-cache-target https://example.com  # Set the production origin manually
 ```
 
-Requires a custom domain (zone analytics are unavailable on `*.workers.dev`) and `CLOUDFLARE_API_TOKEN` with Zone.Analytics read permission.
+Requires a custom domain (zone analytics are unavailable on `*.workers.dev`) and `CLOUDFLARE_API_TOKEN` with **Zone > Analytics > Read** and **Zone > Zone > Read** permissions for that zone.
+
+For typed config projects, declare the custom domain with `domains: ["example.com"]` on the Worker in `cloudflare.config.ts`. The first domain in the generated Build Output is used for both analytics and staged warming. Wrangler projects retain domain selection from their configured routes and deployed triggers. Use `--warm-cache-target https://example.com` to override the origin. Add `--warm-cache-certify` to require reusable cache hits before promotion, or `--no-promote` to leave the warmed version at 0% traffic for verification.
+
+Use the traffic-aware flag on its own to apply the coverage and route limits. Combining it with `--warm-cache` retains full build-discovered warming. See the [caching guide](https://vinext.dev/docs/guides/caching) for all selection controls and requirements.
+
+The previous `--experimental-traffic-aware-warm-cache`, `--experimental-tpr`, and `--tpr-*` names remain supported as aliases.
 
 #### Custom Vite configuration
 
@@ -517,6 +547,7 @@ These are deployed to Cloudflare Workers and updated on every push to `main`:
 | Nextra Docs            | Nextra docs site (MDX, App Router)                                                                               | [nextra-docs-template.vinext.workers.dev](https://nextra-docs-template.vinext.workers.dev)       |
 | App Router (minimal)   | Minimal App Router on Workers                                                                                    | [app-router-cloudflare.vinext.workers.dev](https://app-router-cloudflare.vinext.workers.dev)     |
 | Pages Router (minimal) | Minimal Pages Router on Workers                                                                                  | [pages-router-cloudflare.vinext.workers.dev](https://pages-router-cloudflare.vinext.workers.dev) |
+| Static export          | [Hybrid App/Pages Router site](examples/static-export) served as assets only                                     | [static-export.vinext.workers.dev](https://static-export.vinext.workers.dev)                     |
 | RealWorld API          | REST API routes example                                                                                          | [realworld-api-rest.vinext.workers.dev](https://realworld-api-rest.vinext.workers.dev)           |
 | Benchmarks Dashboard   | Build performance tracking over time (D1-backed)                                                                 | [vinext.dev/benchmarks](https://vinext.dev/benchmarks)                                           |
 | App Router + Nitro     | App Router deployed via Nitro (multi-platform)                                                                   | [examples/app-router-nitro](examples/app-router-nitro)                                           |
@@ -593,8 +624,8 @@ Every `next/*` import is shimmed to a Vite-compatible implementation.
 | Standalone output (`output: 'standalone'`) | ✅  | Generates `dist/standalone` with `server.js`, build artifacts, and runtime deps             |
 | `connection()`                             | ✅  | Forces dynamic rendering                                                                    |
 | `"use cache"` directive                    | ✅  | File-level and function-level. `cacheLife()` profiles, `cacheTag()`, stale-while-revalidate |
-| `instrumentation.ts`                       | ✅  | `register()` and `onRequestError()` callbacks                                               |
-| Route segment config                       | 🟡  | `revalidate`, `dynamic`, `dynamicParams`. `runtime` and `preferredRegion` are ignored       |
+| `instrumentation.ts`                       | ✅  | `register()`, `onRequestError()`, and [framework tracing](docs/tracing.mdx)                 |
+| Route segment config                       | 🟡  | `revalidate`, `dynamic`, `dynamicParams`, `runtime` (not placement). No `preferredRegion`   |
 
 ### Configuration
 
@@ -638,6 +669,15 @@ One caveat: modules whose JSX is lowered earlier in the pipeline are not memoize
 
 vinext automatically loads dotenv files for `dev`, `build`, `start`, and `deploy`.
 
+Vite evaluates all static config imports before plugin hooks, regardless of import order.
+`vinext dev` and `vinext build` preload dotenv from the project root before handing off to Vite,
+preserving the old CLI's config-time behavior. Direct `vite dev` and `vite build` do not. For
+config-time values that work with either command, use Vite's
+[`loadEnv(mode, process.cwd(), "")`](https://vite.dev/config/#using-environment-variables-in-config)
+in a config factory and read its returned values rather than relying on `process.env` in a static
+import. The empty prefix includes server-only variables; use your custom `envDir` in place of
+`process.cwd()` if you have one.
+
 Load order matches Next.js (highest priority first):
 
 1. Existing `process.env` values (shell/CI)
@@ -648,8 +688,9 @@ Load order matches Next.js (highest priority first):
 
 Modes:
 
-- `vinext dev` uses `development`
-- `vinext build`, `vinext start`, and `@vinext/cloudflare deploy` use `production`
+- `vite dev` uses `development`
+- `vite build`, `vinext start`, and `@vinext/cloudflare deploy` use `production`
+- `vinext dev` and `vinext build` use the corresponding mode, including `--mode` overrides
 
 Variable expansion (`$VAR` / `${VAR}`) is supported.
 
@@ -672,49 +713,82 @@ The cache is pluggable. The default `MemoryCacheHandler` works out of the box. S
 Instead of wiring up cache handlers imperatively from a worker entry, you can declare them in the `vinext()` plugin config. The `@vinext/cloudflare` package ships Cloudflare adapters for this:
 
 - **`kvDataAdapter()`** (`@vinext/cloudflare/cache/kv-data-adapter`) — backs the `"use cache"` data cache with a Workers KV namespace.
-- **`cdnAdapter()`** (`@vinext/cloudflare/cache/cdn-adapter`) — serves page-level ISR from the Cloudflare Workers Cache (`ctx.cache`) instead of from the origin.
+- **`workersCacheCdnAdapter()`** (`@vinext/cloudflare/cache/workers-cache-cdn-adapter`) — serves page-level ISR from the Cloudflare Workers Cache (`ctx.cache`) instead of from the origin.
+- **`staticAssetsAdapter()`** (`@vinext/cloudflare/cache/static-assets-adapter`) — packages locally prerendered App Router HTML/RSC into Workers Static Assets and serves it through a read-only page cache.
+- **`responseStoreAdapter()`** (`@vinext/cloudflare/cache/response-store-adapter`) — uses Workers Response Store for both responses and data, with service-binding or self-contained deployment modes. See the [config examples for both modes](docs/caching.mdx#workers-response-store).
 
-The two fill different slots and can be used together:
+The KV and Workers Cache adapters fill different slots and can be used together:
 
 ```ts
-import { defineConfig } from "vite";
-import vinext from "vinext";
-import { cdnAdapter } from "@vinext/cloudflare/cache/cdn-adapter";
+import { workersCacheCdnAdapter } from "@vinext/cloudflare/cache/workers-cache-cdn-adapter";
 import { kvDataAdapter } from "@vinext/cloudflare/cache/kv-data-adapter";
 
-export default defineConfig({
-  plugins: [
-    vinext({
-      cache: {
-        cdn: cdnAdapter(),
-        data: kvDataAdapter(),
-      },
-    }),
-  ],
+vinext({
+  cache: {
+    cdn: workersCacheCdnAdapter(),
+    data: kvDataAdapter(),
+  },
 });
 ```
 
-The KV data adapter reads `env[binding]` at runtime, so add the matching KV namespace to your `wrangler.jsonc`:
+The KV data adapter reads `env[binding]` at runtime. Configure its namespace and the Workers Cache entrypoints in `cloudflare.config.ts`. Here, `existingExports` is your current Worker's `exports` object, or `{}` if it has none:
 
-```jsonc
-{
-  "kv_namespaces": [{ "binding": "VINEXT_KV_CACHE", "id": "<your-namespace-id>" }],
-}
-```
-
-`binding` defaults to `VINEXT_KV_CACHE`, so `kvDataAdapter()` with no options works as long as that's your binding name. Other options: `appPrefix` (namespace cache keys to isolate multiple apps in one KV namespace), `ttlSeconds` (default KV `expirationTtl`, default 30 days), and `tagCacheTtlMs` (in-memory tag-invalidation cache TTL, default 5s).
-
-`cdnAdapter()` takes no options, but the Workers Cache only exposes `ctx.cache` when `cache.enabled` is set in `wrangler.jsonc`:
-
-```jsonc
-{
-  "cache": { "enabled": true },
-}
+```ts
+import { bindings } from "cf/config";
+import { createWorkersCacheConfig } from "@vinext/cloudflare/cache/config";
+
+const cache = await createWorkersCacheConfig();
+
+defineWorker({
+  // ...existing Worker settings
+  ...cache,
+  env: {
+    // ...existing bindings
+    ...cache.env,
+    VINEXT_KV_CACHE: bindings.kv(),
+  },
+  exports: { ...existingExports, ...cache.exports },
+});
 ```
 
-While the data adapter can store entries and serve HIT/STALE itself, the CDN adapter delegates serving to Cloudflare's edge: the origin renders fresh responses and tags them with `Cache-Tag`, and `revalidateTag()` / `revalidatePath()` purge the edge through `ctx.cache.purge({ tags })`. See [examples/workers-cache](examples/workers-cache) for both adapters wired up together.
-
-Each builder returns a plain, serializable `{ adapter, options }` descriptor — **it never touches the Workers runtime**, so nothing throws at build or dev time when bindings aren't available. The actual adapter (and its `env` binding lookup) is instantiated lazily on the first request.
+`binding` defaults to `VINEXT_KV_CACHE`, so `kvDataAdapter()` with no options works as long as that's your binding name. Other options: `appPrefix` (namespace cache keys to isolate multiple apps in one KV namespace), `ttlSeconds` (default KV `expirationTtl`, default 30 days), `tagCacheTtlMs` (in-memory tag-invalidation cache TTL, default 5s), and `entryCacheTtlSeconds` (optional KV edge-cache TTL for entry reads; tag markers keep KV's default).
+
+For immutable build output, configure `prerender: true` with `cache: { cdn: staticAssetsAdapter() }`. The adapter copies prerendered HTML, RSC, and metadata responses into the configured client assets output and reads them from the `ASSETS` binding at runtime. Writes and invalidations are no-ops; a new deployment replaces the cached responses. Run `vinext init --platform=cloudflare --cdn-cache=static-assets` to configure the binding and Worker-first routing that prevents direct access to private cache artifacts; see [Static Assets response cache](docs/caching.mdx#static-assets-response-cache) for manual setup.
+
+When `workersCacheCdnAdapter()` is used in a Cloudflare build, vinext emits two Worker
+entrypoints and configures Workers Cache only on the response entrypoint. The
+default entrypoint keeps caching disabled so middleware and request-time routing
+run on every request. `createWorkersCacheConfig()` declares these policies and
+the version metadata binding in the source config; vinext does not rewrite them
+in the Cloudflare Build Output. For KV-only caching, omit the helper and keep
+the KV binding. See the [adapter configuration examples](docs/caching.mdx).
+
+The generated version metadata binding lets staged discovery and warming verify
+the uploaded Worker version. Pass the same `versionMetadataBinding` to
+`workersCacheCdnAdapter()` and `createWorkersCacheConfig()` only when the deployment needs a
+custom binding name.
+
+`vinext-cloudflare deploy --warm-cache` performs the two-stage
+upload and makes one final cache-fill request per admitted identity by default.
+Add `--warm-cache-certify` only to opt into a second, header-only request that
+must prove every planned entry reusable before promotion.
+
+While the data adapter can store entries and serve HIT/STALE itself, the CDN adapter delegates serving to Cloudflare's edge: the origin renders fresh responses and tags them with `Cache-Tag`, and `revalidateTag()` / `revalidatePath()` purge the edge through `ctx.cache.purge({ tags })`. See [examples/response-store-demo](examples/response-store-demo) for the Workers Response Store adapter.
+
+The response entrypoint adds a transport-only digest of the complete stage
+identity to its Workers Cache URL. That internal key is independent of zone
+Cache Rules and prevents distinct representation, rewrite, or interception
+identities from colliding. With a staged deploy (`--warm-cache`),
+App Router pages its cacheability manifest certifies static leave the query
+string out of their identity, so queries of the page share one entry, as in
+Next.js. Interception RSC requests, and responses that a `next.config`
+`headers()` rule makes cacheable, keep the query. See [Query strings](docs/caching.mdx#query-strings).
+
+Adapter declarations do not access the Workers runtime, so nothing throws at
+config-evaluation or dev time when bindings are unavailable. Builders may also
+provide platform-specific output hooks; `workersCacheCdnAdapter()` adds the response-stage
+Worker exports, while the source config helper declares their cache policies. Runtime adapters (and
+their `env` binding lookups) are instantiated lazily on the first request.
 
 Registration is wired into **every router and runtime** — App Router and Pages Router, on Cloudflare Workers as well as the Node.js server (`vinext start`) and dev. It self-guards (instantiated once per isolate) and is resilient: if an adapter can't initialize on a given runtime (e.g. a KV binding doesn't exist on the Node server), vinext logs a warning and falls back to the default handler instead of failing requests.
 

package/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,25 @@
+# Third-party licenses
+
+## ua-parser-js
+
+MIT License
+
+Copyright (c) 2012-2021 Faisal Salman <f@faisalman.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,25 @@
+import "node:module";
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+export { __commonJSMin, __toESM };

package/dist/build/action-owner-manifest.d.ts

@@ -3,7 +3,7 @@ import { Rollup } from "vite";
 import { RscPluginManager } from "@vitejs/plugin-rsc";
 //#region src/build/action-owner-manifest.d.ts
 type ActionOwnerRoute = Pick<AppRoute, "errorPath" | "errorPaths" | "forbiddenPath" | "forbiddenPaths" | "layoutErrorPaths" | "layouts" | "loadingPath" | "loadingPaths" | "notFoundPath" | "notFoundPaths" | "pagePath" | "parallelSlots" | "pattern" | "siblingIntercepts" | "templates" | "unauthorizedPath" | "unauthorizedPaths">;
-type ActionOwnerRouteReachability = Map<string, {
+export type ActionOwnerRouteReachability = Map<string, {
   clientReferenceImportIds: Set<string>;
   serverReferenceIds: Set<string>;
 }>;
@@ -12,8 +12,8 @@ type ActionOwnerReferenceMaps = {
   clientReferenceMetaMap: RscPluginManager["clientReferenceMetaMap"];
   serverReferenceMetaMap: RscPluginManager["serverReferences"]["metaMap"];
 };
-declare function actionOwnerRouteEntryIds(route: ActionOwnerRoute): string[];
-declare function collectReachableActionReferences(options: {
+export declare function actionOwnerRouteEntryIds(route: ActionOwnerRoute): string[];
+export declare function collectReachableActionReferences(options: {
   canonicalizeModuleId?: (id: string) => string;
   getModuleInfo: (id: string) => ActionOwnerModuleInfo | null;
   roots: readonly string[];
@@ -21,22 +21,21 @@ declare function collectReachableActionReferences(options: {
   clientReferenceImportIds: Set<string>;
   serverReferenceIds: Set<string>;
 };
-declare function collectRscActionReachability(options: {
+export declare function collectRscActionReachability(options: {
   canonicalizeModuleId?: (id: string) => string;
   getModuleInfo: (id: string) => ActionOwnerModuleInfo | null;
   routes: readonly ActionOwnerRoute[];
   sharedRoots?: readonly string[];
 } & ActionOwnerReferenceMaps): ActionOwnerRouteReachability;
-declare function resolveClientReferenceImportIds(options: {
+export declare function resolveClientReferenceImportIds(options: {
   canonicalizeModuleId?: (id: string) => string;
   resolveId: (id: string) => Promise<string | null>;
   routeReachability: ActionOwnerRouteReachability;
 }): Promise<void>;
-declare function addClientActionReachability(options: {
+export declare function addClientActionReachability(options: {
   canonicalizeModuleId?: (id: string) => string;
   getModuleInfo: (id: string) => ActionOwnerModuleInfo | null;
   routeReachability: ActionOwnerRouteReachability;
 } & ActionOwnerReferenceMaps): void;
-declare function buildActionOwnerManifest(routeReachability: ActionOwnerRouteReachability): Record<string, string[]>;
-//#endregion
-export { ActionOwnerRouteReachability, actionOwnerRouteEntryIds, addClientActionReachability, buildActionOwnerManifest, collectReachableActionReferences, collectRscActionReachability, resolveClientReferenceImportIds };
+export declare function buildActionOwnerManifest(routeReachability: ActionOwnerRouteReachability): Record<string, string[]>;
+//#endregion

package/dist/build/action-owner-manifest.js

@@ -39,6 +39,17 @@ function actionOwnerRouteEntryIds(route) {
 		])
 	].filter((value) => typeof value === "string");
 }
+function memoizeModuleInfo(getModuleInfo) {
+	const cache = /* @__PURE__ */ new Map();
+	return (id) => {
+		let info = cache.get(id);
+		if (info === void 0) {
+			info = getModuleInfo(id);
+			cache.set(id, info);
+		}
+		return info;
+	};
+}
 function collectReachableActionReferences(options) {
 	const canonicalizeModuleId = options.canonicalizeModuleId ?? ((id) => id);
 	const clientReferenceImportIds = /* @__PURE__ */ new Set();
@@ -62,17 +73,18 @@ function collectReachableActionReferences(options) {
 	};
 }
 function collectRscActionReachability(options) {
+	const getModuleInfo = memoizeModuleInfo(options.getModuleInfo);
 	const routeReachability = new Map(options.routes.map((route) => [route.pattern, collectReachableActionReferences({
 		canonicalizeModuleId: options.canonicalizeModuleId,
 		clientReferenceMetaMap: options.clientReferenceMetaMap,
-		getModuleInfo: options.getModuleInfo,
+		getModuleInfo,
 		roots: actionOwnerRouteEntryIds(route),
 		serverReferenceMetaMap: options.serverReferenceMetaMap
 	})]));
 	if (options.sharedRoots?.length) routeReachability.set("*", collectReachableActionReferences({
 		canonicalizeModuleId: options.canonicalizeModuleId,
 		clientReferenceMetaMap: options.clientReferenceMetaMap,
-		getModuleInfo: options.getModuleInfo,
+		getModuleInfo,
 		roots: options.sharedRoots,
 		serverReferenceMetaMap: options.serverReferenceMetaMap
 	}));
@@ -80,21 +92,27 @@ function collectRscActionReachability(options) {
 }
 async function resolveClientReferenceImportIds(options) {
 	const canonicalizeModuleId = options.canonicalizeModuleId ?? ((id) => id);
+	const resolvedIdsByImportId = /* @__PURE__ */ new Map();
 	for (const reachability of options.routeReachability.values()) {
 		const resolvedImportIds = /* @__PURE__ */ new Set();
 		for (const importId of reachability.clientReferenceImportIds) {
-			const resolvedId = await options.resolveId(importId) ?? importId;
-			resolvedImportIds.add(canonicalizeModuleId(resolvedId));
+			let resolvedId = resolvedIdsByImportId.get(importId);
+			if (resolvedId === void 0) {
+				resolvedId = canonicalizeModuleId(await options.resolveId(importId) ?? importId);
+				resolvedIdsByImportId.set(importId, resolvedId);
+			}
+			resolvedImportIds.add(resolvedId);
 		}
 		reachability.clientReferenceImportIds = resolvedImportIds;
 	}
 }
 function addClientActionReachability(options) {
+	const getModuleInfo = memoizeModuleInfo(options.getModuleInfo);
 	for (const reachability of options.routeReachability.values()) {
 		const clientReachability = collectReachableActionReferences({
 			canonicalizeModuleId: options.canonicalizeModuleId,
 			clientReferenceMetaMap: options.clientReferenceMetaMap,
-			getModuleInfo: options.getModuleInfo,
+			getModuleInfo,
 			roots: [...reachability.clientReferenceImportIds],
 			serverReferenceMetaMap: options.serverReferenceMetaMap
 		});

package/dist/build/assets-ignore.d.ts

@@ -16,7 +16,7 @@
  * patterns with `.gitignore` semantics (via the `ignore` package), so the bare
  * `.vite` entry excludes the directory and everything beneath it.
  */
-declare const DEFAULT_VINEXT_ASSET_IGNORE_PATTERNS: readonly string[];
+export declare const DEFAULT_VINEXT_ASSET_IGNORE_PATTERNS: readonly string[];
 /**
  * Ensure a `.assetsignore` in `clientDir` contains every pattern in `patterns`.
  *
@@ -27,6 +27,5 @@ declare const DEFAULT_VINEXT_ASSET_IGNORE_PATTERNS: readonly string[];
  * @returns `true` when the file was created or modified, `false` when it already
  *          covered every requested pattern.
  */
-declare function ensureAssetsIgnore(clientDir: string, patterns?: readonly string[]): boolean;
-//#endregion
-export { DEFAULT_VINEXT_ASSET_IGNORE_PATTERNS, ensureAssetsIgnore };
+export declare function ensureAssetsIgnore(clientDir: string, patterns?: readonly string[]): boolean;
+//#endregion

package/dist/build/clean-output.d.ts

@@ -8,6 +8,5 @@ type CleanBuildOutputResult = {
   cleaned: boolean;
   outDir: string;
 };
-declare function cleanBuildOutput(options: CleanBuildOutputOptions): CleanBuildOutputResult;
-//#endregion
-export { cleanBuildOutput };
+export declare function cleanBuildOutput(options: CleanBuildOutputOptions): CleanBuildOutputResult;
+//#endregion