Exposing plugin HTML transforms for Backend Integration

[fpapado]

Is your feature request related to a problem? Please describe.

I am wondering whether Vite can expose a plugin's index HTML transforms for Backend Integration. This seems separate (but on a spectrum?) from SSR, especially considering cases where the base template is not built up-front. I am mostly thinking out loud; feel free to close this if it is a non-goal, or if the SSR integration is the way to go for this.

I have been integrating Vite into an Eleventy project (Eleventy is a static site generator, so all the content is built once).
At the moment, I am following the Backend Integration guide. The integration was clear to me; there is no HTML entry, only a JS one. Thus, we must add the base scripts, split where we get their information in development (point script to Vite dev server running separately) and production (template script ourselves by reading manifest.json) and so on. So far, so good.

Different plugins, such as plugin-react-refresh or plugin-legacy transform the index HTML (when one exists). They might add a preamble to the head or output different script tags and inline scripts. The Backend Integration guide mentions that you should add these manually, with information that you either know up-front, or from the manifest. While this is doable, it feels brittle to use. The react-refresh preamble is ok, but the plugin-legacy scripts are more complicated. This led me to think about describing the index HTML transforms.

Describe the solution you'd like

I am wondering whether it is possible to expose the index HTML transforms in a manifest-adjacent file, when the entry is not HTML. For example, I notice that the Plugin API allows plugins to return an array of tag descriptor objects ({ tag, attrs, children }). This would be the equivalent of plugin-legacy saying "hey, if you are templating these into HTML, go ahead and add script[nomodule] before the body, this inline script in the head" etc.

The templates could then read that file, and add the tags to the correct place. Of course, they could ignore it and do the templating manually. I imagine this as giving plugins a way to express what ideally should happen. However, it might be that the plugins do not have enough information to express the transforms as {tags, attrs, children}, or that it might be more code for them to maintain, I am not sure! That's why I'm writing this 🙂

Describe alternatives you've considered

For the concrete issue I am facing here, an alternative I am exploring is having Vite target an HTML template entry, which Eleventy will use as the base for each page. I think this is workable, but it means I must template the base as HTML instead of a Nunjucks file, which I'm using in the rest of the site. I think it is also workable to do all the tag templating manually, mirroring the plugin source and any information from the manifest.

I also tried using the SSR APIs, which also require the up-front building of a template by Vite. I have not explored this avenue fully. However, I imagine that a solution which exposes the transforms in a manfiest-adjacent file will also help projects who do not run JS for their server-side rendering.

Additional context

I tried searching for various combinations of HTML transform, Backend Integration, manifest and templating, but could not find a matching issue. This makes me think that I'm either bad at searching, or this is a very niche feature. Let me know either way, I sense that I'm overthinking this 😁

[bluwy]

I find this general issue among many SSR metaframeworks too. The issue with the proposal is that we can't output a chunk that exposes a transform function as a Vite plugin is in object form, so you'd have to export the full code. This also includes node etc which may not work in non-node environments, e.g. Cloudflare workers. Among other things, it bloats up the bundle and runtime performance that I don't think it's the right approach forward.

The other safe way is to call transformIndexHtml during build-time, so you're still within a node environment, but it would only work for prerendered pages. Many metaframeworks support hybrid pages that could be rendered dynamically so having transformIndexHtml causing this inconsistency isn't ideal too.

I think either ways the latter idea may still be helpful, which is tracked at #2270. Closing in favour of that.