Environment API

[patak-dev]

We decided to release the Environment API branch as [email protected] (we'll continue regularly releasing new alpha patches).

The changes started by the Runtime API are now prompting a complete review of the way Vite handles environments (client, SSR, workerd, etc). We were originally going to release this branch as [email protected] but the changes are now too big for a minor so we're going to start working on the next major directly with it. We're probably going to have ~2 months of alpha period and once we feel confident with the stability of the new APIs, we'll kick the beta.

If you are building a framework or are working in a Runtime (like the Cloudflare team), the next months are going to be very important to get the APIs right and serve as the base for the next iteration. We're thinking on lifting Vite's responsibilities to be able to share more in the ecosystem. For example, we're introducing the concept of a ViteBuilder that lets frameworks orchestrate all the environment builds they need to get a single vite build command to build the whole app. This means changing our stance on the "framework-as-a-plugin" pattern (SvelteKit, Remix, QwikCity, etc), and making it a first class pattern from Vite 6 forward.

Check out the current Environment API docs and give us feedback. This discussion is a good place to gather it, please share your impressions and PoCs as you test.

If you think someone you know would be interested in helping us testing and creating prototypes (Workerd framework-agnostic integrations, RSC, etc), please contact them so they can get involved.

Resources:

• Environment API PR
• Environment API Docs

Previous discussions:

• Runtime API PR
• Runtime API Feedback discussion
• Initial Docs PR
• Initial Implementation PR

History:

Check out @antfu's Dev SSR on Nuxt post, explaining @pi0's Dev Bundler idea that led to the creation of vite-node. Anthony used vite-node to as the engine of Vitest. After revamping it, @sheremet-va added a revised version of vite-node in Vite Core in Vite 5.1. The Environment API is a new iteration, deeply integrating the features vite-node provided in Vite's API.

[hi-ogawa]

I started to experimenting with workerd/miniflare in

• chore: workerd environment prototype hi-ogawa/vite-environment-examples#14

Overall approach and code doesn't look so different from my previous one with vite runtime https://github.com/hi-ogawa/vite-plugins/tree/main/packages/vite-node-miniflare, but regarding the usability of current environment API, I have a few comments:

• it looks like environments.(env).dev.createEnvironment needs to be synchronous, but I think I can structure the code more easily if it simply allows async.
• it looks like deps optimization is injecting createRequire banner, so I'm still adding ssr.target: "webworker".
  • actually this might be already fixed by 0ea8be9. I'll try it later.
• I tried RemoteEnvironmentTransport/RemoteRunnerTransport with Workerd websocket and it nicely worked for small code, but I got "too large websocket payload" error when testing it on react ssr example (I think frandiox talked about this issue for hydrogen integration). For now, I gave up using transport and simply went back to using fetch for transport.fetchModule.

I haven't tested server hmr yet, but I plan to continue experiment on that later.

[hi-ogawa]

@patak-dev Thanks for the update. Asynchronous createEnvironment is working very nice. With this, the most of code lives in createWorkerdDevEnvironment and using other hooks are not necessary.

Expanding on my previous 2nd comment, I'd like to disable this createRequire banner injected to deps optimization output. It looks like I still need to use deprecated ssr.target: "webworker" in [email protected]. I suppose you're still figuring out what to do with node/webCompatible, but just wanted to let you know.

vite/packages/vite/src/node/optimizer/index.ts

Lines 781 to 786 in 7254175

	banner:
	platform === 'node'
	? {
	js: `import { createRequire } from 'module';const require = createRequire(import.meta.url);`,
	}
	: undefined,

---

If your environment transport doesn't support two-way communication, use your own custom function. There is no way for us to provide a wrapper here as far as I understand -

@sheremet-va Yeah, I didn't mean to be an environment API feedback, but just wanted to mention as a general caveat for people trying workerd.

Well, I thought so, but now looking at mrbbot's vitest integration, he seems to figure out a way around it by implementing createChunkingSocket!
https://github.com/cloudflare/workers-sdk/blob/2789f26a87c769fc6177b0bdc79a839a15f4ced1/packages/vitest-pool-workers/src/shared/chunking-socket.ts#L9-L15

Either way, it's a custom runtime side constraints, so I don't think Vite side needs to do anything for this.

[hi-ogawa]

Any general feedback about how the new API feels to use?

Regarding environment agnostic SSR https://deploy-preview-16089--vite-docs-main.netlify.app/guide/api-vite-environment.html#environment-agnostic-ssr, the plugin is still registering middleware automatically, but the main feature is mostly moved to createWorkerdDevEnvironment, so this might give flexibility for frameworks to integrate workerd.

Currently I organized API in this way:

WorkerdDevEnvironment

export type WorkerdDevEnvironment = 
  DevEnvironment & {
    api: {
      dispatchFetch: (entry: string, request: Request) => Promise<Response>
    }
  }

export function createWorkerdDevEnvironment(
  server: ViteDevServer,
  name: string,
  // allow miniflare customization inspired by vitest pool
  // https://developers.cloudflare.com/workers/testing/vitest-integration/configuration/
  workerdOptions: {
    miniflare: { ... },
    wrangler: { configPath?: string }
  }
): Promise<WorkerdDevEnvironment>;

Then vitePluginWorkerd only consume the environment like this:

configureServer

{
  configureServer(server) {
    const devEnv = server.environments["workerd"] as WorkerdDevEnvironment;
    const nodeHandler = webHandlerToNodeHandler(
      (req) => devEnv.api.dispatchFetch(someEntry, req),
    );
    return () => {
      server.middlewares.use(nodeHandler);
    };
  },
}

Also thanks to cloudflare team's effort on Vitest pool, there are new features in wrangler such as unstable_getMiniflareWorkerOptions. This allows using wrangler config similar to getPlatformProxy, so this is one step toward getPlatformProxy-like dev experience.

All that said, how workerd feature is exposed to main vite process side is still only a minimal request handler, so the situation might not change drastically in terms of easy of existing complex frameworks to integrate.

One thing I plan to look at next is whether it's possible to implement something similar to "magic proxy" cloudflare/miniflare#639 so that main vite process can transparently import modules from workerd just like createServerModuleRunner.

[hi-ogawa]

@sheremet-va I implemented HMRChannel in somewhat abstract manner as createSimpleHMRChannel https://github.com/hi-ogawa/vite-environment-examples/blob/3de66bfc7269cd0426a6e83a03cd451e059ff604/examples/workerd/src/plugin.ts#L191

Actually I'm not sure if it's correct (I haven't tested custom event), but it feels like it's mostly a boilerplate. Is this something like Vite can provide builtin utility like transport?

[sheremet-va]

Yeah, we can implement a separate transport option for HMR to hide the boilerplate.

[patak-dev]

I'd like to disable this createRequire banner injected to deps optimization output. It looks like I still need to use deprecated ssr.target: "webworker" in [email protected]

This should now work without ssr.target in [email protected]. webCompatible and nodeCompatible are stop gaps though. We need to add finer grained options for most of the branches they are involved with.

[hi-ogawa]

This is a feedback about a minor cosmetics of logging. Currently, simple SSR setup (like the one in a playground) shows somewhat puzzling logs:

pnpm -C playground/environment-react-ssr dev

# after changing a shared file src/root.tsx
3:03:13 PM [vite] page reload src/root.tsx
3:03:13 PM [vite] page reload src/root.tsx
[vite] program reload

On my react-server example with client hmr plugin, it gets more complex:

pnpm -C examples/react-server dev

# initial log from two server environments
[vite] connected.
[vite] connected.

# after changing a shared file
3:13:02 PM [vite] hmr update /home/hiroshi/code/personal/vite-environment-examples/examples/react-server/src/routes/_client.tsx
3:13:02 PM [vite] page reload src/routes/_client.tsx
[vite] program reload

In "two Vite servers" demo, I have customLogger and prefix, then the log became easier to understand.

{
  customLogger: createLogger(undefined, {
    prefix: "[react-server]",
    allowClearScreen: false,
  }),
}

3:13:02 PM [react-server] page reload src/routes/test/page.tsx

Is there a way to add log prefix like this for new environments? or maybe can each log have a prefix of [vite:(env)] by default?

[patak-dev]

Good point. I think we should do this by default. The logger has a prefix option defaulting to [vite]. Maybe we should make each environment has its own logger with a different prefix. I wonder if we even need the vite there. Maybe just [client]/[ssr] is less noisy and different enough from other logs. This would be good not only for HMR, but in general for logs of any plugin, the deps optimizer, etc.

@sheremet-va I see the HMRLogger in module-runner doesn't have a prefix, and [vite] is harcoded. This makes sense for the browser client.ts as the logs are in the browser console. For SSR, we should also have the environment name there.

[hi-ogawa]

When running moduleRunner.import(<non-optimized-dep>) in custom environment, I get a following error:

Error: Vite Internal Error: registerMissingImport is not supported in dev custom

I haven't dive into the code yet. For now, I made a reproduction here #16426 since you might know something.

[mfulton26]

Can service workers be a supported environment too? I'd like to build an offline web app almost the same as an online one. If server side rendering can be bundled to be used as service worker side rendering then an offline web app doesn't need to bundle and run most (if any) JavaScript in the document scope.

[patak-dev]

I think that could work. I was also thinking about Web Workers. Maybe we should also implement them using environments. We have some issues right now with the way they are implemented that could be cleaned up with them. If you have some time to try out the alpha, that would be great to inform our decisions with the API @mfulton26

[Snugug]

This is awesome to see. Wanted to ask about how something like injecting new globals or CSPs would work to emulate other environments, like extensions or a Kiosk mode. It'd be great to be able to add APIs not normally exposed in-browser and that may required server-side backing (like chrome.enterprise.deviceAttributes into the dev environment this way, or test how an app would work under the Isolated Web App CPSs