docs: per-environment state in plugins

[patak-dev]

Description

Adds a section about per-environment state handling in plugins. We didn't have a reference to perEnvironmentStartEndDuringDev: true without this section.

This was already document under future breaking changes here https://vite.dev/changes/shared-plugins-during-build.html, including the perEnvironmentState helper.

I didn't include the perEnvironmentState helper in the guide because I'm unsure if we should be promoting it. The explicit Map<Environment, State> may be better and less magical. The helper currently takes a init function to create the state of each environment, but a reset should also be added to buildStart for build watch mode leading to the state being inited twice (just a detail, but still)

A note, during build watch, this plugin counts how many modules have been re-transformed. We use this pattern in our internal plugins, but for many use cases it could break if the whole state is busted on buildStart and only some modules get re-transformed and people expect the whole state to be there. In the case of keeping state per module, I don't know if we have a good answer that is compatible with watch mode.

Maybe we shouldn't promote per environment state at all and instead have users return meta info in hooks. This documents what we have been doing internally and how the ecosystem also did things even without environments so probably it is fine to have it (same issue between state and build watch mode could happen only for the client). Long term, @sapphi-red maybe this is something to review for rolldown-vite and how state in plugins would be shared between Rust and JS, how it interacts with build watch mode, and the future full-bundle mode too.

[sapphi-red]

I don't know if we have a good answer that is compatible with watch mode.

Maybe skipping state.set if this.meta.watchMode is true can work?

I'll set this PR as a draft, as maybe we shouldn't promote per environment state at all and instead have users return meta info in hooks. But I think that isn't enough. @sapphi-red maybe this is something to review for rolldown-vite and how state in plugins should be shared between Rust and JS, how it interacts with build watch mode, and the future full-bundle mode too.

Currently, Rolldown does not share state between Rust and JS. We haven't investigated around that topic yet. I guess it'll take some time.

[patak-dev]

I don't know if we have a good answer that is compatible with watch mode.

Maybe skipping state.set if this.meta.watchMode is true can work?

In that case, the perEnvironmentState helper is good with the init function and skipping resetting it on buildStart. Both cases may be useful for different things, it depends what should happen when rebuilding.

One issue when there is no reset is that old modules state are kept around when the deleting a file for example. At the end, all these cases are the same as they have always been for plugin state even taking environments out of the picture (just with client, and state defined in the plugin, it is the same case). We never documented how that should work so far, so maybe we should keep things in the same way and don't document this either for now.

[sapphi-red]

Let's go without perEnvironmentState for now. I think we’ll have a clearer picture of watch mode in the near future.