Prototype: createServer API for local Worker sessions

[edmundhung]

Fixes n/a.

Here is a prototype createServer() API for starting local Worker sessions from Node.js.

The goal is to explore a stable replacement path for unstable_startWorker() and unstable_dev() that:

• works well for integration testing
• supports multiple workers in one session
• works across Wrangler, Vite and OpenNext project
• can also serve as the programmatic API for starting local dev server sessions

The prototype keeps the implementation small by wrapping the existing DevEnv runtime used by wrangler dev / wrangler pages dev, while exposing a narrower API shape.

• listen() to start the server,
• close() to dispose the resoruces,
• getWorker(name?) to interact with a dedicate worker,

For wrangler users, they will need to create a worker server by specifying the configPath. This will start a dev server that builds the project right away:

const server = createServer({
  workers: [
    { config: "wrangler.primary.jsonc" },
    { config: "wrangler.auxiliary.jsonc" },
  ],
});

For vite users, we will rely on the deploy config / redirected config instead and skip the build.

It might be worth making wrangler build output a deploy config as well so wrangler user could build it once before starting any tests and then reuse the build throughout.

const server = createServer({
  workers: [
    { deployConfig: true },
  ]
});

This also includes a create-server fixture demonstrating the intended testing workflow for both Wrangler and Vite projects, including outbound request mocking via MSW.

---

• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows:
  • Additional testing not necessary because:
• Public documentation
  • Cloudflare docs PR(s):
  • Documentation not necessary because:

A picture of a cute animal (not mandatory, but encouraged)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9ceb824

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@12785

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@12785

miniflare

npm i https://pkg.pr.new/miniflare@12785

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@12785

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@12785

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@12785

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@12785

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@12785

wrangler

npm i https://pkg.pr.new/wrangler@12785

commit: 9ceb824