feat: v6 - Environment API

[patak-dev]

Description

Note

Check out the Environment API Docs

We're starting a new PR for the Environment API work in progress proposal for v6 to have a clean slate for reviews and discussions now that the implementation and docs are more stable.

This PR merges the work done in:

• feat: environment api #16129
• docs: environment API proposal #16089

Refer to the discussions in these PRs for context. If you have general feedback about the APIs, let's use this discussion so we can have proper threads:

• Environment API #16358

If you have comments about the implementation or would like to collaborate a feature, fix, test, or docs, please comment in this PR as an usual review or send a PR against the v6/environment-api branch.

Ecosystem Compatibility

These projects are failing in CI because of known reasons.

Framework	Reason	PR
VitePress	using internal server._importGlobMap, which is moved	vuejs/vitepress#3706

[stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[antfu]

/ecosystem-ci run

[antfu]

/ecosystem-ci run

[vite-ecosystem-ci]

📝 Ran ecosystem CI on 909fe28: Open

suite	result	latest scheduled
astro	❌ failure	✅ success
histoire	❌ failure	✅ success
marko	❌ failure	✅ success
previewjs	❌ failure	❌ failure
qwik	❌ failure	✅ success
rakkas	❌ failure	✅ success
remix	❌ failure	✅ success
sveltekit	❌ failure	❌ failure
vike	❌ failure	❌ failure
vite-plugin-svelte	❌ failure	✅ success
vitepress	❌ failure	✅ success
vitest	❌ failure	❌ failure

✅ analogjs, ladle, laravel, nuxt, quasar, unocss, vite-plugin-pwa, vite-plugin-react, vite-plugin-react-pages, vite-plugin-react-swc, vite-plugin-vue, vite-setup-catalogue

[vite-ecosystem-ci]

📝 Ran ecosystem CI on 909fe28: Open

suite	result	latest scheduled
astro	❌ failure	✅ success
histoire	❌ failure	✅ success
marko	❌ failure	✅ success
previewjs	❌ failure	❌ failure
qwik	❌ failure	✅ success
rakkas	❌ failure	✅ success
remix	❌ failure	✅ success
sveltekit	❌ failure	❌ failure
vike	❌ failure	❌ failure
vite-plugin-svelte	❌ failure	✅ success
vitepress	❌ failure	✅ success
vitest	❌ failure	❌ failure

✅ analogjs, ladle, laravel, nuxt, quasar, unocss, vite-plugin-pwa, vite-plugin-react, vite-plugin-react-pages, vite-plugin-react-swc, vite-plugin-vue, vite-setup-catalogue

[sheremet-va]

/ecosystem-ci run

[vite-ecosystem-ci]

📝 Ran ecosystem CI on 611ce5c: Open

suite	result	latest scheduled
astro	❌ failure	✅ success
histoire	❌ failure	✅ success
marko	❌ failure	✅ success
previewjs	❌ failure	❌ failure
qwik	❌ failure	✅ success
rakkas	❌ failure	✅ success
remix	❌ failure	✅ success
sveltekit	❌ failure	❌ failure
vike	❌ failure	❌ failure
vitepress	❌ failure	✅ success
vitest	❌ failure	❌ failure

✅ analogjs, ladle, laravel, nuxt, quasar, unocss, vite-plugin-pwa, vite-plugin-react, vite-plugin-react-pages, vite-plugin-react-swc, vite-plugin-svelte, vite-plugin-vue, vite-setup-catalogue

[patak-dev]

/ecosystem-ci run

[vite-ecosystem-ci]

📝 Ran ecosystem CI on e91e269: Open

suite	result	latest scheduled
astro	❌ failure	✅ success
histoire	❌ failure	✅ success
marko	❌ failure	✅ success
previewjs	❌ failure	❌ failure
qwik	❌ failure	✅ success
rakkas	❌ failure	✅ success
remix	❌ failure	✅ success
sveltekit	❌ failure	❌ failure
vike	❌ failure	❌ failure
vitepress	❌ failure	✅ success
vitest	❌ failure	❌ failure

✅ analogjs, ladle, laravel, nuxt, quasar, unocss, vite-plugin-pwa, vite-plugin-react, vite-plugin-react-pages, vite-plugin-react-swc, vite-plugin-svelte, vite-plugin-vue, vite-setup-catalogue

[dario-piotrowicz]

are these options correct?

this fetchModule is what the DevEnvironment class uses right?

these options seem to be specifically targeting node? (given the .cjs extension and the main field usage)

should this be make more generic, or actually could this be made configurable?
(so that DevEnvironment instances could tweak these options as needed?)

[dario-piotrowicz]

Or actually, shouldn't this inherit from the environment's options, some fields are indeed inherited:
https://github.com/vitejs/vite/pull/16471/files/2b3329d4aa0b91a5920527a9712b82ae59becba3#diff-fde6fc19368b69a4726cb38039db6dee6abf54bc69e1484c4f6e6c9d952acd9dR40-R42

[sheremet-va]

These are the same options that were used for ssrLoadModule before. It might be a good idea to provide a way to customize it, but you can also intercept the fetchModule call at any time

[dario-piotrowicz]

what do you mean by intercepting the call? 🙏

Right now what I am doing is creating a new DevEnvironment instance (source):

const devEnv = new ViteDevEnvironment(name, config, {
  hot,
}) as DevEnvironment;

and then using the instance's fetchModule in order to let vite apply its module resolution (source):

const result: any = await devEnv.fetchModule(...(args as [any, any]));

So that I can feed this result back to the module runner (source):

transport: {
  fetchModule: async (...args) => {
    const response = await env.__viteFetchModule.fetch(
      new Request('http://localhost', {
        method: 'POST',
        body: JSON.stringify(args),
      }),
    );
    const result = response.json();
    return result as any;
  },
},

is there a different way which would allow me to fetch the modules with my own resolve options?

[dario-piotrowicz]

@sheremet-va me and Igor have been looking more into this and we agree that the default node environment should preserve the ssrLoadModule behavior.

The fetchModule implementation in this class is however generally useful for custom environments, and in fact it's already exposed as part of the Environment API, so custom environments get to benefit from it.

For the custom environments to however truly benefit from this implementation, the environment config needs to be honored as I've pointed out above.

In order to preserve the behavior for the default node environment, we just need to ensure that it's default node environment is configured in a way that preserves the original ssrLoadModule implementation.

Would this work for you or are we missing anything else that complicates the matter? Thank you

[sheremet-va]

Yes, I agree that it needs to be customizable.

[sheremet-va]

I guess here we can only expose these:

• mainFields -> externalMainFields
• extensions -> externalExtensions
• tryEsmOnly -> externalTryEsmOnly

All other fields are related to externalization and not to the environment. Is this ok for you?