Environment API

[patak-dev]

We decided to release the Environment API branch as vite@6.0.0-alpha.x (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 vite@5.3.0-alpha.0 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 vite@6.0.0-alpha.1. 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 vite@6.0.0-alpha.1

This should now work without ssr.target in vite@6.0.0-alpha.2. 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

[cysabi]

hey! 👋
i'm not quite sure if this is exactly relevant, but i thought i would share my situation and ask if this is something that this new api is intended to help with (or if im just blind as a bat to something in the docs!! heh)

i was building a really simple spa with solid, and i wanted to change the vite build output to include the statically generated app + a hydration script instead of the empty shell.
because of how small this was (transform the built index.html using 2 lines of code), i was curious if it was possible by writing a really simple vite plugin.

but i wasn't really able to find an easy and simple way to do this at all!!
plugins can't import modules and have them resolved by vite the same way your index.html can, but your index.html file can't exactly import some ssr script that renders itself to a string.
so there's no good intuitive way to modify an entry file, while being in the context of your module graph!

perhaps customizing the behavior of vite's dev and build feel so difficult because the module resolution is so tightly coupled to your entry file, and perhaps this coupling is exactly what makes implementing ssr with vite so complicated in the first place.

I am not quite settled on the correct way to solve this, but one of my ideas is perhaps the ability to set a jsx file (with exports) as your entry file, then write a plugin that has access to those exports and returns an html string? not really the most happy with that though, im curious what ideas other people have!

At the end of the day, I would like basic ssg functionality (at least in solid) to be easily implementable by end users in your own 5-line vite plugin.

[brillout]

Seems like the assets/ directory upon SSR build isn't generated anymore? This makes Vike's CI fail.

The Vite Env API docs don't mention assets, so I'm not sure whether something is supposed to change in that regard.

(Very excited and looking forward to the Vite Env API 👀)

[lazarv]

hi! I'm experimenting with the Vite Env API in @lazarv/react-server and while I had some issues about using different root for envs, I had much more benefit from using the Env API vs using multiple instances of Vite servers.

My feedback on Env API:

• I'm using the Env API only for the dev server, for production build I'm invoking Vite's build programmatically as I have multiple stages
• clean architecture to support multiple environments with a base configuration and some overrides
• but it's not 100% clean where to override specific parts of the configuration for different envs
• environments should support different root and environment specific operations should not use the servers config, it should use the envs "forked" config
• I had some issues with module externalization especially using the RemoteRunnerTransport, I had to patch transport.fetchModule to make it work properly in my use case
• watcher/hot/HMR setup for environments could be more developer friendly
• might be good to have environment specific plugins, I had to change my custom plugin to check which environment is the current one and skip if not applicable, this should be the responsibility of the environment, as plugins could not know on which envs they are running, but it would be very easy to create a plugin helper to apply the plugin only on some specific envs
• client/ssr environment is hard-coded right now and env names need to follow the default envs, like renaming "client" to "browser" env seems not to be possible right now

All-in-all, even in it's current state, Env API is the way to go, I'll continue to enhance my configuration and keep experimenting with it. Nice work!

[sheremet-va]

I had some issues with module externalization especially using the RemoteRunnerTransport, I had to patch transport.fetchModule to make it work properly in my use case

Can you give more information on what the problem is?

[lazarv]

I had to do the following patch on the transport, as I experienced issues because of how React resolution should work with the "react-server" loader condition and I had to externalize these React modules in the worker thread this way as the Vite module resolution on the main thread was wrong. Might be some wrong setup on my side, but it's fairly complex to support 3 envs using 2 different React versions while I want to resolve all React imports to the one used by the framework.

const remoteTransport = new RemoteRunnerTransport({
  send: (data) => {
    parentPort.postMessage({ type: "import", data });
  },
  onMessage: (listener) =>
    parentPort.on("message", (payload) => {
      if (payload.type === "import") {
        listener(payload.data);
      }
    }),
  timeout: 5000,
});
remoteTransport.fetchModule = (id, importer) => {
  if (["react", "react/jsx-dev-runtime", "react-dom/client"].includes(id)) {
    return { externalize: id };
  }
  return remoteTransport.resolve("fetchModule", id, importer);
};

[lazarv]

Regarding

I had some issues about using different root for envs

I create a PR #17394, but I have issues with the tests, if anyone interested to take a look, I would really appreciate help on that one, thanks!