[wrangler] Add wrangler compile for self-hosting Workers on standalone workerd#14294
[wrangler] Add wrangler compile for self-hosting Workers on standalone workerd#14294threepointone wants to merge 5 commits into
wrangler compile for self-hosting Workers on standalone workerd#14294Conversation
Add a reusable, tested `standalone/` module that turns a Miniflare-assembled `Workerd.Config` into a self-contained bundle runnable under bare `workerd serve`: - `emitConfigText()` — faithful text Cap'n Proto emitter (embeds modules/blobs, fails loud on unsupported shapes). - `toStandaloneConfig()` — production transform: reachability-prune dev-only services, repoint `globalOutbound` to `internet`, single `http` socket, relativize `disk` paths, prune unused runtime extensions, emit assets disk read-only. - `emitStandaloneBundle()` — writes the config (`text` or `binary`), embeds, and copies `disk` contents. - `Miniflare.prototype.unstable_getConfig()` — read the fully-assembled config without re-deriving the service graph. Co-authored-by: Cursor <cursoragent@cursor.com>
- Add a `"standalone": boolean` config field (validated + normalized) declaring a Worker targets a self-hosted workerd runtime rather than Cloudflare. - Add `standalone-support.ts`, a single source of truth classifying each binding type as supported (stateless/pure-workerd) or unsupported (stateful/platform) for the standalone MVP. Exported via `getStandaloneSupport`. Co-authored-by: Cursor <cursoragent@cursor.com>
Add an experimental `wrangler compile` command that builds a Worker into a self-contained `workerd` bundle (config, embedded modules, on-disk static assets, a version-pinned Dockerfile, an entrypoint, a README, and a capability report) runnable on any server outside of Cloudflare. - Reuses the `deploy --dry-run` bundling pipeline, drives Miniflare to assemble the resolved config, and emits the standalone bundle via the miniflare core. - `--outdir`, `--force`, `--format text|binary`, and `--serve` (+ `--port`/`--ip`) to run the exact emitted artifact locally under the bundled workerd binary. - `unstable_compileStandalone()` programmatic API (shared with the Vite plugin). - `wrangler deploy` errors when `standalone` is set; `wrangler dev --standalone` warns about bindings unsupported by standalone workerd. Co-authored-by: Cursor <cursoragent@cursor.com>
Add `cloudflare({ standalone: true | { outDir?, force? } })`. When set, `vite
build` emits the same self-contained workerd bundle as `wrangler compile`,
reusing the shared `unstable_compileStandalone()` core (no duplicated assembly
or emit logic). A guarded post-build hook handles Vite 6 and 7/8 timing so
exactly one path fires per build.
Co-authored-by: Cursor <cursoragent@cursor.com>
Changeset (wrangler/miniflare/vite-plugin minor) and the design RFC for the standalone self-hosted workerd bundles feature, included for discussion. Co-authored-by: Cursor <cursoragent@cursor.com>
🦋 Changeset detectedLatest commit: 3e344ce The changes in this PR will be included in the next version bump. This PR includes changesets to release 6 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
✅ All changesets look good |
![ask-bonk[bot]](https://avatars.githubusercontent.com/in/2454580?s=60&v=4){kind=small}
There was a problem hiding this comment.
I'm Bonk, and I've done a quick review of your PR.
This adds wrangler compile (plus a shared miniflare emit/transform core and a Vite standalone build mode) to emit a self-contained workerd serve bundle. The plumbing is well-organized and the alpha scoping is clear. A few things stand out, ranked by severity:
- Secrets are baked into the emitted bundle in plaintext, silently.
secret_textis markedsupported, and the compile path resolves bindings viaunstable_getMiniflareWorkerOptions->getBindings()->getVarsForDev(), which loads.dev.vars/.envvalues assecret_text. Those get embedded verbatim intoconfig.capnp/config.bin(and the generatedDockerfiledoesCOPY . /app). The README/COMPILE_REPORT actively encourage committing/Dockerizing the output, with no warning that real secrets may now be sitting in plaintext in a checked-in artifact. At minimum this needs a prominent warning at compile time and in the README; ideally local-dev secrets shouldn't be auto-embedded without an explicit opt-in. pruneUnusedExtensionsuses naive substring matching for liveness, which can mis-prune. See inline comment.serveStandaloneBundleswallows the termination signal in its exit code. See inline comment.
Details inline.
| // Pure value/config bindings + static assets are baked directly into the | ||
| // generated `workerd` config and work without any Cloudflare backend. | ||
| plain_text: "supported", | ||
| secret_text: "supported", |
There was a problem hiding this comment.
secret_text: "supported" means secrets are treated as fully fine for standalone. But in the compile path these are resolved from .dev.vars/.env via getVarsForDev() and embedded verbatim into the emitted config.capnp/config.bin (which the generated Dockerfile then COPY . /apps, and the README tells users to commit). There is no warning anywhere that local secrets end up in plaintext in a shippable/committable artifact.
At minimum, please surface a clear warning at compile time and in the generated README when any secret_text binding is embedded. Consider whether local-dev secrets should be embedded at all without an explicit opt-in flag — silently baking .dev.vars into a distributable bundle is a footgun.
| const live = collectWrappedModuleNames(keptServices); | ||
| const workerSources = collectWorkerSources(keptServices); | ||
| for (const name of moduleByName.keys()) { | ||
| if (workerSources.some((source) => source.includes(name))) { |
There was a problem hiding this comment.
Liveness here is decided by source.includes(name) — a raw substring scan over the bundled worker JS. This is fragile in two directions:
- A module whose name is a substring of another live module's name (e.g.
emailvsemail-extra) will be kept (or dropped) incorrectly. - Any string literal in user code that merely mentions a module name keeps that extension, even if it's never imported.
The same substring issue exists in the transitive closure below (source.includes(candidate)). Since over-pruning silently produces a broken bundle and under-pruning bloats it, consider matching against actual import specifiers (e.g. parse import statements / match quoted specifiers) rather than includes, or at least document this as a known heuristic limitation in the function's JSDoc.
| let exited = false; | ||
| let exitError: Error | undefined; | ||
| const exitPromise = new Promise<void>((resolve) => { | ||
| child.on("exit", (code, signal) => { |
There was a problem hiding this comment.
When --serve is interrupted, the forwarded SIGINT/SIGTERM causes the child to exit with signal set (not a code), so exitError stays undefined and runStandaloneCompile resolves normally — wrangler exits 0 even though it was terminated. For a long-running serve command this matters for shell/CI/container semantics (e.g. a supervisor expecting 130/143). Consider re-raising the signal (process.kill(process.pid, signal)) or setting a non-zero process.exitCode when the child was killed by a signal.
|
Review posted successfully to PR #14294. Summary of what I flagged:
|
create-cloudflare
@cloudflare/deploy-helpers
@cloudflare/kv-asset-handler
miniflare
@cloudflare/pages-shared
@cloudflare/unenv-preset
@cloudflare/vite-plugin
@cloudflare/vitest-pool-workers
@cloudflare/workers-auth
@cloudflare/workers-editor-shared
@cloudflare/workers-utils
wrangler
commit: |
2 participants
Fixes #[insert GH or internal issue link(s)].
Note
Draft for discussion. This is an alpha, internal-only feature — see "Release posture" below. The full design lives in
RFC-wrangler-compile.md, included in this PR for review.What & why
workerd(the runtime behind Cloudflare Workers) has always been runnable outside of Cloudflare, but almost nobody does it because you have to hand-author a Cap'n Proto config and wire up features (static assets, etc.) yourself.This PR adds
wrangler compile: it takes a Worker + its config and emits a self-contained, Node-free bundle that runs anywhereworkerdruns viaworkerd serve— AWS, Hetzner, Railway, Render, Fly, bare metal, a container, etc. Static assets (with_headers/_redirects/SPA handling) are wired up out of the box.The key insight: Miniflare already assembles a real
Workerd.Configand its simulators are pure workerd Workers. The Node process is only needed for dev-only scaffolding. So most of the work here is stripping Miniflare's output down to a portable, production-shaped config and emitting it as a bundle.You can also opt in via
"standalone": trueinwrangler.json(orcloudflare({ standalone: true })in the Vite plugin). When set,wrangler devwarns about bindings that work locally but aren't supported by standalone workerd, andwrangler deployerrors (since the Worker targets a self-hosted runtime, not Cloudflare).What this could enable
Scope of this PR (alpha)
workerd serve(bothtextandbinaryconfig formats).miniflare;wrangler compileand the Vite plugin both call oneunstable_compileStandalone()path.Dockerfile,$PORT-awareentrypoint.sh,README.md, and a capabilityCOMPILE_REPORT.md.Release posture
Internal/alpha only; public release is gated on cloudflare/workerd#6780 landing. While alpha, nothing is stable — output layout, config shape, and CLI flags may all change. The command is
status: experimentaland unsupported bindings are a hard error (bypass with--force).How it's wired
packages/miniflare/src/standalone/— text + binary emitters, the production transform (reachability pruning, outbound repoint, read-only assets disk, extension pruning), andemitStandaloneBundle(). NewMiniflare.prototype.unstable_getConfig()seam.packages/workers-utils/src/config/—"standalone"config field +standalone-support.tsbinding matrix.packages/wrangler/src/compile/— the command +unstable_compileStandalone();deployguard;devwarning.packages/vite-plugin-cloudflare/—standalonebuild mode (thin adapter onto the shared core).A picture of a cute animal (not mandatory, but encouraged)
🦫
Made with Cursor