feat: fetchable dev environments

[teemingc]

This PR changes the dev, preview, build analysis and prerender to run inside of the configured Vite SSR environment. This required the following fundamental changes:

1. Avoiding Node.js imports in the runtime

• Some of our utilities had to be moved to a separate file to avoid importing Node.js modules. Others had to be recreated to avoid adding another dependency if we want the same functionality in a Node-agnostic environment.
• node:fs is a requirement but we import it in the main process instead and communicate the results back to the Vite SSR environment.
• We can't use AsyncLocalStorage.enterWith because it's a Node.js-only experimental API

2. Replacing Vite's ssrLoadModule

The Vite docs recommendation is to create a ModuleRunner or the RunnableDevEnvironment instance to achieve a similar functionality but these don't work with Cloudflare's environment. There's also no strict contract for environments to make these available to us so they can't be relied on. We solve this in two different ways:

• We use Vite's import.meta.hot.on in the SSR environment to listen for events from the main process, compute the result, and send it back.
• Instead of importing the Server class from the build output in the main process, we spin up a Vite development server with the build output but proxy the Server class by intercepting module resolution with Vite's resolveId hook. Starting a dev server and sending a request or HMR event seems to be the only way to run a module in the environment.

3. Communication between the main process (where Vite runs) and the SSR environment (where user code runs)

The two points before this makes this a requirement. Now we'll detail the different types of communication that exist as a result:

One way communication

• Main process to SSR environment. e.g., when we detect a server asset import from a Vite hook, we can update the server manifest in the environment using environments.ssr.hot.send. This helps us retain synchronous access to the filesystem from a non-Node environment such as checking if a filename exists as a key in the server assets map. We can also construct virtual modules with serialised data that the can be imported and accessed in the environment.
• SSR environment to main process. e.g., when an error occurs on the server, we use import.meta.hot.send so that the main process can then create a Vite error overlay in the browser. This replaces our loudSsrLoadModule utility.

Two way communication

• Main process to SSR environment and back to the main process. Previously we could just run ssrLoadModule to run some code in Vite's pipeline and get a result back. Now, we have to ensure the SSR environment has an import.meta.hot.on event listener attached, emit an event, compute in the environment, and receive the results back in the main process through environments.ssr.hot.on and Promise.withResolvers to await the result. This is used for retrieving remote function info, etc. Alternatively, we can also proxy the Server class during analysis and prerendering to respond with our environment computed result as mentioned earlier.
• SSR environment to main process and back to the environment. This requires the operation to be asynchronous if it wasn't already. We also can't re-use the two-way import.meta.hot approach above because Cloudflare's workerd doesn't like responding to requests from a context created by import.meta.hot.on. Therefore, we use fetch to send a request to the running Vite dev server, configure the Vite dev server using the configureServer hook to intercept the request via vite.middlewares.use, and respond with the computed result. This is primarily used for getting CSS to inline to avoid FOUC during dev, finding out which param matchers exist from the filesystem, or even checking if a feature should be allowed by the adapter.supports function which we can't serialise.

Most of the import.meta.hot and fetch style communication requires serialising and deserialising data using devalue.

Future PRs

• adapter-static environment that uses sirv on the build output instead of running the SSR server
• adapter-node environment that allows using a custom entry point similar to after building
• adapter-netlify environment to run things in serverless/edge mode?

---

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
• This message body should clearly illustrate what problems it solves.
• Ideally, include a test that fails without this PR but passes with it.

Tests

• Run the tests with pnpm test and lint the project with pnpm lint and pnpm check

Changesets

• If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

Edits

• Please ensure that 'Allow edits from maintainers' is checked. PRs without this option may be closed.

[changeset-bot]

🦋 Changeset detected

Latest commit: 454ceda

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@sveltejs/kit	Major

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

[svelte-docs-bot]

Preview: https://svelte-dev-git-preview-kit-15574-svelte.vercel.app/

[teemingc]

AFAIK there's no need to fix stack traces inside environments as Vite handles that

[teemingc]

helps avoids a type error when importing this in the prerender_entry.js file

[teemingc]

Might be better to add adapter config options such as adapter.vite.customDev and adapter.vite.customPreview which default to false and can be set to true to disable the default SSR handlers during vite dev and vite preview

[Rich-Harris]

The recent on main and version-3 are proving rather difficult to merge into this branch. The nub of the problem is that dynamic environment variables need to be set before anything gets imported from $app/env/*, and there are some brain-bending circular dependencies involved. Trying to figure it out

[Rich-Harris]

Alright, rewinding the merge, since I fucked things up beyond repair. Sorry 😬 Will see if I can get it right on the second attempt, though I'm a little worried that the new explicit env stuff is going to pose a real challenge

[teemingc]

I’ll take a look too if you haven’t had another go at it already

[Rich-Harris]

It's all working now, just needed to point to __SERVER__/env.js. One of those obvious-in-hindsight things that takes several hours of headbashing to realise

[Nic-Polumeyv]

Heads up for when this rebases. The eager import('/@vite/client') added in render.js is gated on esm-env DEV, the same pattern that caused #16008. Verified here, a NODE_ENV=staging build puts @vite/client in the prerendered output. #16023 swaps that for an import.meta.hot guard in the generated app.js.