@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
md 102 lines 8.66 KB
Rendered Raw
1 # Parity with `@cloudflare/vite-plugin`
2
3 Alchemy's Vite plugin replaces `@cloudflare/vite-plugin` (checked against
4 **1.65.0**, the catalog version). Frameworks are built against the official
5 plugin's behavior, so anything they can observe must match. This file is the
6 inventory of that surface: every behavior is **matched** (with the test that
7 pins it), **different on purpose** (with the reason), or **out of scope**.
8
9 Wrangler-specific behavior is out of scope: Alchemy configures Workers in
10 code, so `wrangler.json`, `.dev.vars`/`.env` loading, the Build Output
11 Specification, deploy config redirects, tunnels, keyboard shortcuts, agent
12 hints, update checks and the local explorer/observability UIs have no
13 counterpart.
14
15 ## How parity is enforced
16
17 | Test | What it checks |
18 | --- | --- |
19 | [`test/parity/config.test.ts`](./test/parity/config.test.ts) | Resolves one project with both plugins (`serve` and `build`, with and without `nodejs_compat`/`nodejs_als`, with user overrides, in production) and compares what frameworks read: each environment's `resolve`, `define`, `build`, `optimizeDeps`, the client environment, `appType`, `server.fs.deny`. |
20 | [`test/parity/build.test.ts`](./test/parity/build.test.ts) | Builds five project shapes with both plugins and compares the output: every file in `dist/`, entry chunk names and exports. |
21 | [`test/parity/constants.test.ts`](./test/parity/constants.test.ts) | Compares the runtime pieces ported verbatim (handler keys, additional module rules, `cloudflare:*` built-ins, Sandbox preview origins) with the installed release. |
22 | `packages/integration-tests/test/Cloudflare/Website/Vite*.test.ts` | The plugin's playgrounds and create-cloudflare's templates, deployed and under `alchemy dev`. |
23
24 Upgrading `@cloudflare/vite-plugin` in the catalog re-runs all three
25 differential tests against the new release, so upstream drift in config,
26 build output or the ported runtime fails CI here instead of in an app.
27 Fixes ported from upstream `main` before a release ships them are listed in
28 [`test/parity/ahead-of-release.ts`](./test/parity/ahead-of-release.ts), which
29 the differential tests ignore until the installed release catches up.
30
31 ## Inventory
32
33 ### Plugin identity and options
34
35 | Behavior | Status | Test |
36 | --- | --- | --- |
37 | Frameworks detect the plugin by a `vite-plugin-cloudflare` name prefix (React Router, vinext, Vike's `@universal-deploy`, Flue) | Matched (`vite-plugin-cloudflare:alchemy`) | `plugin-name.test.ts` |
38 | An official `cloudflare()` left in the config (or added by an async factory, e.g. RedwoodSDK) is neutralized | Matched | `plugin-name.test.ts`, `ViteTemplates.test.ts` |
39 | The `config` customizer of a neutralized `cloudflare()` still runs (Flue's `flueWorkerConfig()`) | Matched | `plugin-name.test.ts`, `examples/cloudflare-flue` |
40 | `rsc: { serverHandler: false }` for `@vitejs/plugin-rsc` | Matched | React Router RSC fixtures |
41 | Worker settings from `wrangler.json` / the customizer's result | Different: declared on the Website resource | — |
42 | `auxiliaryWorkers`, `persistState`, `remoteBindings`, `inspectorPort` | Different: separate `Cloudflare.Worker` resources, Alchemy state, `Alchemy.remote()` | — |
43 | `experimental.prerenderWorker` | Out of scope (experimental); prerendering through the preview server is matched | `ViteBuild.test.ts` |
44
45 ### Resolved config
46
47 | Behavior | Status | Test |
48 | --- | --- | --- |
49 | `appType: "custom"`; `server.fs.deny` (Vite's, credentials, key stores, `.wrangler`) | Matched, plus Alchemy's state and stack files | `config.test.ts`, `ViteRuntime.test.ts` (sensitive files) |
50 | Worker environment `resolve` (conditions, `noExternal`, built-ins) | Matched | `config.test.ts` |
51 | `cloudflare:durable-objects` is a runtime built-in | Matched ahead of the release (upstream `main`, after 1.65.0) | `constants.test.ts`, `config.test.ts` via `test/parity/ahead-of-release.ts` |
52 | `define`: `process.env.NODE_ENV`; `process.env` as `{}` without `nodejs_compat` | Matched | `config.test.ts`, `ViteRuntime.test.ts` (NODE_ENV) |
53 | `build`: target (`es2026` on Rolldown), `cssTarget`, manifest, source maps, `emitAssets`, `copyPublicDir`, `ssr`, output dir, `index` entry input | Matched | `config.test.ts`, `build.test.ts` |
54 | `optimizeDeps`: entries, `development` condition, Node.js and `cloudflare:*` excluded | Matched | `config.test.ts` |
55 | esbuild `supported.using` scoped to Worker environments (Vite 6/7) | Matched | `config.test.ts` (Rolldown); code path mirrors upstream |
56 | Assets-only projects declare no Worker environments | Matched | `config.test.ts`, `build.test.ts` |
57
58 ### Build
59
60 | Behavior | Status | Test |
61 | --- | --- | --- |
62 | Default `buildApp`: Worker environments, then the client; a client with no entry builds for `public/` or Worker-imported assets; imported assets move to the client output | Matched | `build.test.ts` |
63 | A user's own `buildApp` is kept | Matched | `ViteRuntime.test.ts` (custom buildApp) |
64 | Additional modules (`.wasm`, `.bin`, `.txt`, `.html`, `.sql`, subpath imports), `.wasm?init` | Matched | `build.test.ts`, `ViteRuntime.test.ts` (additional modules) |
65 | Node.js compat: unenv aliases, injected globals and polyfills | Matched | `ViteNodeCompat.test.ts` |
66 | Unexpected Node.js imports warn without `nodejs_compat` (build and dev) | Matched | `dev-plugin.test.ts`, `ViteNodeCompat.test.ts` (als) |
67 | `using` kept native | Matched | `build.test.ts`, `ViteBuild.test.ts` |
68 | Deployed modules are the output as written to disk; `.vite/` metadata isn't deployed | Matched | `ViteTemplates.test.ts` (Vike) |
69
70 ### Dev server
71
72 | Behavior | Status | Test |
73 | --- | --- | --- |
74 | Module runner in workerd: HMR, source-mapped stacks, sealed exports, `cloudflare:workers` `env` without internal bindings | Matched | `ViteRuntime.test.ts` (importable env, error page) |
75 | `__VITE_ENVIRONMENT_RUNNER_IMPORT__` for child environments (`import.meta.viteRsc.loadModule`) | Matched | `ViteRuntime.test.ts` (child environment), React Router RSC |
76 | Export wrappers for `WorkerEntrypoint`, `DurableObject`, `WorkflowEntrypoint` and their handler keys | Matched | `constants.test.ts`, `ViteRuntime.test.ts` (entrypoints, Durable Objects, Workflows) |
77 | Restart when the entry's export types change | Matched | `dev-export-types.test.ts` |
78 | Restart when an additional module file changes | Matched | `dev-assets.test.ts` |
79 | Uncaught `fetch` errors on Vite's error page | Matched | `ViteRuntime.test.ts` (error page) |
80 | An unresolvable `main` fails the dev start | Matched | `ViteRuntime.test.ts` (config changes) |
81 | `run_worker_first` routing ahead of Vite's middlewares; the router and asset worker | Matched | `ViteAssetRouting.test.ts` |
82 | HTML through `transformIndexHtml`, `public/` HTML raw, `server.headers` on assets | Matched | `dev-assets.test.ts` |
83 | Vite's bundled dev mode (`experimental.bundledDev`) | Matched | `ViteRuntime.test.ts` (bundled dev) |
84 | The Worker's `ASSETS` binding runs through Vite's middlewares | Matched | `dev-assets.test.ts` |
85 | WebSockets to the Worker; Vite's HMR socket left alone unless from a Sandbox preview origin; a socket another `upgrade` listener answers is left to it | Matched | `websockets.test.ts`, `constants.test.ts`, `ViteRuntime.test.ts` (WebSockets) |
86 | A refused WebSocket upgrade | Different: the Worker's response reaches the client (upstream resets the socket) | `websockets.test.ts` |
87 | `/cdn-cgi/local/*` trigger endpoints and the legacy `/cdn-cgi/mf/*`, `/cdn-cgi/handler` paths | Matched | `ViteRuntime.test.ts` (scheduled and email) |
88 | Public URL from the dev server's host, port and HTTPS | Matched | `ViteStreaming.test.ts` (HTTPS) |
89 | `X-Forwarded-Host`, `X-Forwarded-Proto` (case-insensitive), `ctx.access` from `dev.access` | Matched | `forwarded-host.test.ts`, `ViteRuntime.test.ts` (headers, Access) |
90 | The Worker's response status text (dev and preview) | Matched (upstream `main`, after 1.65.0) | `dev-proxy.test.ts` |
91 | Repeated `Set-Cookie` request headers reach the Worker as separate values | Matched (upstream `main`, after 1.65.0) | `dev-proxy.test.ts` |
92 | Outbound `fetch`: `CF-Worker`, no `CF-Connecting-IP`, `cf.image` | Matched | `ViteRuntime.test.ts` (CF-Worker, cf.image) |
93 | Restart after a workerd crash | Matched | `ViteRuntime.test.ts` (workerd crashes) |
94 | Containers built from a Dockerfile | Matched | `ViteRuntime.test.ts` (containers) |
95 | Alchemy's runtime variables (`ALCHEMY_*`) in `env` and `process.env` | Different: Alchemy's runtime reads them; documented on `env` | `ViteNodeCompat.test.ts` (process-populated-env) |
96 | `/__debug` inspector page, structured log levels | Out of scope (presentation) | — |
97
98 ### Preview
99
100 | Behavior | Status | Test |
101 | --- | --- | --- |
102 | `vite preview` serves the built Worker and its assets | Matched | `preview-plugin.test.ts`, `ViteBuild.test.ts` (prerendering) |