@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 8.66 KB

Parity with @cloudflare/vite-plugin

Alchemy's Vite plugin replaces @cloudflare/vite-plugin (checked against 1.65.0, the catalog version). Frameworks are built against the official plugin's behavior, so anything they can observe must match. This file is the inventory of that surface: every behavior is matched (with the test that pins it), different on purpose (with the reason), or out of scope.

Wrangler-specific behavior is out of scope: Alchemy configures Workers in code, so wrangler.json, .dev.vars/.env loading, the Build Output Specification, deploy config redirects, tunnels, keyboard shortcuts, agent hints, update checks and the local explorer/observability UIs have no counterpart.

How parity is enforced

Test What it checks
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.
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.
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.
packages/integration-tests/test/Cloudflare/Website/Vite*.test.ts The plugin's playgrounds and create-cloudflare's templates, deployed and under alchemy dev.

Upgrading @cloudflare/vite-plugin in the catalog re-runs all three differential tests against the new release, so upstream drift in config, build output or the ported runtime fails CI here instead of in an app. Fixes ported from upstream main before a release ships them are listed in test/parity/ahead-of-release.ts, which the differential tests ignore until the installed release catches up.

Inventory

Plugin identity and options

Behavior Status Test
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
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
The config customizer of a neutralized cloudflare() still runs (Flue's flueWorkerConfig()) Matched plugin-name.test.ts, examples/cloudflare-flue
rsc: { serverHandler: false } for @vitejs/plugin-rsc Matched React Router RSC fixtures
Worker settings from wrangler.json / the customizer's result Different: declared on the Website resource —
auxiliaryWorkers, persistState, remoteBindings, inspectorPort Different: separate Cloudflare.Worker resources, Alchemy state, Alchemy.remote() —
experimental.prerenderWorker Out of scope (experimental); prerendering through the preview server is matched ViteBuild.test.ts

Resolved config

Behavior Status Test
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)
Worker environment resolve (conditions, noExternal, built-ins) Matched config.test.ts
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
define: process.env.NODE_ENV; process.env as {} without nodejs_compat Matched config.test.ts, ViteRuntime.test.ts (NODE_ENV)
build: target (es2026 on Rolldown), cssTarget, manifest, source maps, emitAssets, copyPublicDir, ssr, output dir, index entry input Matched config.test.ts, build.test.ts
optimizeDeps: entries, development condition, Node.js and cloudflare:* excluded Matched config.test.ts
esbuild supported.using scoped to Worker environments (Vite 6/7) Matched config.test.ts (Rolldown); code path mirrors upstream
Assets-only projects declare no Worker environments Matched config.test.ts, build.test.ts

Build

Behavior Status Test
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
A user's own buildApp is kept Matched ViteRuntime.test.ts (custom buildApp)
Additional modules (.wasm, .bin, .txt, .html, .sql, subpath imports), .wasm?init Matched build.test.ts, ViteRuntime.test.ts (additional modules)
Node.js compat: unenv aliases, injected globals and polyfills Matched ViteNodeCompat.test.ts
Unexpected Node.js imports warn without nodejs_compat (build and dev) Matched dev-plugin.test.ts, ViteNodeCompat.test.ts (als)
using kept native Matched build.test.ts, ViteBuild.test.ts
Deployed modules are the output as written to disk; .vite/ metadata isn't deployed Matched ViteTemplates.test.ts (Vike)

Dev server

Behavior Status Test
Module runner in workerd: HMR, source-mapped stacks, sealed exports, cloudflare:workers env without internal bindings Matched ViteRuntime.test.ts (importable env, error page)
__VITE_ENVIRONMENT_RUNNER_IMPORT__ for child environments (import.meta.viteRsc.loadModule) Matched ViteRuntime.test.ts (child environment), React Router RSC
Export wrappers for WorkerEntrypoint, DurableObject, WorkflowEntrypoint and their handler keys Matched constants.test.ts, ViteRuntime.test.ts (entrypoints, Durable Objects, Workflows)
Restart when the entry's export types change Matched dev-export-types.test.ts
Restart when an additional module file changes Matched dev-assets.test.ts
Uncaught fetch errors on Vite's error page Matched ViteRuntime.test.ts (error page)
An unresolvable main fails the dev start Matched ViteRuntime.test.ts (config changes)
run_worker_first routing ahead of Vite's middlewares; the router and asset worker Matched ViteAssetRouting.test.ts
HTML through transformIndexHtml, public/ HTML raw, server.headers on assets Matched dev-assets.test.ts
Vite's bundled dev mode (experimental.bundledDev) Matched ViteRuntime.test.ts (bundled dev)
The Worker's ASSETS binding runs through Vite's middlewares Matched dev-assets.test.ts
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)
A refused WebSocket upgrade Different: the Worker's response reaches the client (upstream resets the socket) websockets.test.ts
/cdn-cgi/local/* trigger endpoints and the legacy /cdn-cgi/mf/*, /cdn-cgi/handler paths Matched ViteRuntime.test.ts (scheduled and email)
Public URL from the dev server's host, port and HTTPS Matched ViteStreaming.test.ts (HTTPS)
X-Forwarded-Host, X-Forwarded-Proto (case-insensitive), ctx.access from dev.access Matched forwarded-host.test.ts, ViteRuntime.test.ts (headers, Access)
The Worker's response status text (dev and preview) Matched (upstream main, after 1.65.0) dev-proxy.test.ts
Repeated Set-Cookie request headers reach the Worker as separate values Matched (upstream main, after 1.65.0) dev-proxy.test.ts
Outbound fetch: CF-Worker, no CF-Connecting-IP, cf.image Matched ViteRuntime.test.ts (CF-Worker, cf.image)
Restart after a workerd crash Matched ViteRuntime.test.ts (workerd crashes)
Containers built from a Dockerfile Matched ViteRuntime.test.ts (containers)
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)
/__debug inspector page, structured log levels Out of scope (presentation) —

Preview

Behavior Status Test
vite preview serves the built Worker and its assets Matched preview-plugin.test.ts, ViteBuild.test.ts (prerendering)