Plugin to allow importing processed entry HTML files into JS/TS keeping source maps intact.

[ThinkingPlanely]

Wondering if anybody knows of an existing plugin (or how to make one) that allows importing entry HTML files into JS as a string, keeping source maps intact and waiting until after the entry HTML files have already been processed by Vite before embedding them into to JS.

[aymenhmaidiwastaken]

The reason you won't find one is that the middle part of what you're asking for doesn't exist to wait on — Vite doesn't process non-entry HTML at all.

Checked on Vite 8.2.0 with a partial containing an asset reference and a script tag:

import raw from './partial.html?raw'

emitted chunk:
  contains <img src="./logo.png"> : true      <- untouched source
  contains hashed asset ref       : false     <- never went through asset pipeline
  has sourcemap                   : true

?raw reads the file and hands it to you as a string literal before anything HTML-aware runs. And transformIndexHtml — the hook that does the rewriting you're after — only fires for entry documents:

=== transformIndexHtml fired for ===
   /index.html

  partial.html included? -> false

So there's no "processed" version of an imported partial sitting somewhere that a plugin could pick up later. Ordering a plugin after Vite's HTML handling doesn't help, because for that file the HTML handling never ran.

The good news is your sourcemap concern is already handled: the ?raw import produces a normal JS module and out.js.map is emitted alongside it. Mappings point back into the .html file. There's no separate HTML→JS mapping to preserve beyond that, since the whole file becomes one string literal.

Two ways to actually get processing, depending on what "processed" means for you:

If you want asset URLs resolved and hashed, add the partials as extra Rollup inputs so they go through the HTML pipeline properly, then read the emitted result rather than importing the source:

build: {
  rollupOptions: {
    input: {
      main: 'index.html',
      partial: 'src/partial.html',
    },
  },
}

If you only need the asset references rewritten and don't want extra HTML entry points, a small plugin doing it in transform is less machinery than it sounds — match .html?raw, walk the src/href attributes, and this.emitFile({ type: 'asset' }) each one, substituting the returned reference id. That's the piece a general-purpose plugin would have to do anyway, and it's short because you control which attributes matter for your partials.

Worth saying which one you're after — if it's the second, the shape of your partials (inline scripts? nested imports? just images?) changes how much of that walk you actually need.

[ThinkingPlanely]

I've updated it to say "entry HTML files". That's what I meant originally. I was also thinking maybe the plugin could also auto add the imported files to the entrypoints.

[AmritaMalik]

I think you can achieve this by using a custom Vite plugin with the transformIndexHtml hook.

Vite processes HTML entry files through this hook, and with order: 'post' you can run your transformation after Vite has finished processing the HTML.

Example:

export default function htmlToString() {
return {
name: 'html-to-string',
transformIndexHtml: {
order: 'post',
handler(html) {
return export default ${JSON.stringify(html)}
}
}
}
}

This allows you to get the final processed HTML as a JS string. For source maps, the plugin should return a proper transform result with a map if additional JS transformation is applied.

Vite also supports importing assets as strings using ?raw, but that happens before HTML processing, so a post HTML transform may be more suitable for this use case.

[aymenhmaidiwastaken]

@AmritaMalik order: 'post' doesn't change the scope of the hook, only its position among other plugins' transformIndexHtml handlers. It still only runs for entry documents.

Same test as above, with your exact configuration:

transformIndexHtml: {
  order: 'post',
  handler(html, ctx) { seen.push(ctx.filename) ; return html },
}

=== transformIndexHtml order:'post' fired for ===
   /index.html

  partial.html included? -> false

partial.html is imported from main.js, and the hook never sees it — with 'pre' or 'post'. Vite treats it as a module to be loaded, not as a document to be processed, so there's no HTML pass to run after.

Returning export default ${JSON.stringify(html)} from that hook would also rewrite the entry document into a JS module, which breaks the page rather than producing an importable string.

The two routes that do work are the ones above: add the partials as extra Rollup inputs so they genuinely go through the HTML pipeline, or do the asset-URL rewriting yourself in a transform hook matching .html?raw and emitting each referenced asset with this.emitFile.

[ThinkingPlanely]

@AmritaMalik @aymenhmaidiwastaken I have something that works, except I can't seem to get the source maps to update correctly. I'm trying to use MagicString and have no idea what went wrong. 😔

btw I'm auto adding the html files into the rollup input.

transformIndexHtml: {
    order: "post",
    handler(html, ctx) {
        const htmlBuildPath = buildFolder.joining(ctx.path.slice(1))
        const bundle = ctx.bundle!
        for (const id in bundle) {
            const entry = bundle[id]
            if (entry.type === "chunk") {
                if (entry.code.includes(postfix)) {
                    // Inject HTML into JS:
                    const scriptBuildPath = buildFolder.joining(entry.fileName)
                    const filePath = htmlBuildPath.relativeTo(scriptBuildPath.parent)
                    const newCode = new MagicString(entry.code)
                    const pattern = new RegExp(`import +[a-zA-Z]+ from *"${RegExp.escape(filePath.toString() + postfix)}"`, "g")
                    newCode.replaceAll(pattern, (sub) => {
                        importedHTMLFiles.push(htmlBuildPath)
                        return `let ${sub.split(" ")[1]}=${JSON.stringify(html)}`
                    })
                    if (entry.map) {
                        // TODO: Something isn't working! https://evanw.github.io/source-map-visualization
                        const newMap = newCode.generateMap({
                            source: ctx.path,
                            hires: true,
                            includeContent: true,
                        })
                        const mergedMap: SourceMap = remapping(
                            [JSON.stringify(newMap), JSON.stringify(entry.map)],
                            () => null,
                        )
                        mergedMap.file = entry.map.file
                        Object.assign(entry.map, mergedMap)
                    }
                    entry.code = newCode.toString()
                }
            }
        }
    },
},

The only other way I can think this could work is if I first converted the html file to a js file with a default export, than ran vite again to import the new js file into the chunk. BUT then I'd have to run vite twice, which doesn't seem right.

[barry166]

The sourcemap problem is mostly this line: source: ctx.path.

new MagicString(entry.code) means the original source for that edit map is the already-rendered JS chunk, not the HTML file. If you compose that map with entry.map, make the patch map point back to the chunk file, e.g. source: entry.map?.file ?? entry.fileName and file: entry.fileName; otherwise the unchanged JS in the chunk starts tracing to the HTML entry and remapping has nothing sensible to line up.

If you can move the chunk edit earlier, renderChunk is the cleaner place because Rollup expects { code, map } there and composes the sourcemap for you. This still will not give accurate per-character mappings inside the injected HTML string; for that, the more robust shape is a virtual JS module for the processed HTML (export default ...) and let Rollup bundle that module instead of patching the final chunk.

[ThinkingPlanely]

Thank you for pointing that out! Generating the maps work now, but for some odd reason the Vite still outputs the old source map. I guess I'll have to override the map file in the writeBundle hook or something like that. I don't think I can use render chunk because I have to wait until the html has been processed by vite before inserting it into the js file.

[ThinkingPlanely]

Update: I've got it to work with vite build and now I need to get the plugin to work with vite dev I am not quite sure if this is possible though...

[barry166]

For dev it is possible, but not by waiting for Rollup output: there is no bundle/chunk to patch in dev.

I would make the dev path a virtual module. Store the dev server from configureServer, and when your *.html?processed import is loaded, read the HTML file, run it through await server.transformIndexHtml(url, html), then return a JS module:

return `export default ${JSON.stringify(transformedHtml)}`

Keep the build path separate, or make build emit the same virtual module from the processed Rollup HTML. The key bit is that transformIndexHtml only runs automatically for served HTML entry requests; imported .html modules need your plugin to call the dev transform explicitly.

[ThinkingPlanely]

Ah, yes I didn't think about accessing the dev server in the module loading hook. Thanks for your insight! I think I got it all working now.

[ThinkingPlanely]

Now I need ViteDevServer.tranformIndexHtml to convert URL's to absolute because when then HTML is being imported as text and then inserted into another document the URLs break. I've found someone asked the same question here #13763

[chzaeem47]

I think the remaining URL issue comes from the fact that transformIndexHtml() transforms the HTML relative to the URL you pass to it, but after that HTML is imported as a string and embedded into a different document, its relative URLs no longer have the same base URL.

Instead of trying to rewrite the resulting HTML afterward, you can give transformIndexHtml() a URL that represents the final location/base of the HTML at the point where it will actually be embedded.

For example, in the virtual-module loader:

const html = await fs.promises.readFile(htmlFile, 'utf8')

const transformed = await server.transformIndexHtml(
  targetUrl,
  html,
)

return `export default ${JSON.stringify(transformed)}`

If targetUrl is something like /pages/test/, Vite will resolve URLs such as:

<img src="./logo.svg">
<script type="module" src="./index.ts"></script>

relative to that URL during HTML transformation.

The important distinction is that the URL passed to transformIndexHtml() should represent the HTML document's URL, not the URL of the virtual JS module that happens to import it.

If the final HTML is always embedded into a known document location, another robust option is to make the HTML entries use root-relative URLs in the first place:

<img src="/pages/test/logo.svg">
<script type="module" src="/pages/test/index.ts"></script>

Then the generated HTML doesn't depend on the location where the string is eventually inserted.

For the dev virtual-module approach, I'd structure the plugin roughly like this:

let viteServer: ViteDevServer

export default function htmlAsString() {
  return {
    name: 'html-as-string',

    configureServer(server) {
      viteServer = server
    },

    async load(id) {
      if (!id.endsWith('.html?processed')) {
        return null
      }

      const file = id.slice(0, -'?processed'.length)
      const html = await fs.promises.readFile(file, 'utf8')

      const url = '/' + path.relative(
        server.config.root,
        file
      ).replaceAll(path.sep, '/')

      const transformed = await viteServer.transformIndexHtml(
        url,
        html,
      )

      return `export default ${JSON.stringify(transformed)}`
    },
  }
}

The exact URL mapping will depend on your root/base configuration, but the key is to preserve the relationship:

HTML filesystem path → HTML URL → transformIndexHtml()

rather than using the virtual module's URL as the HTML URL.

Also, I wouldn't run Vite twice. The virtual-module approach is a much better fit because it lets the dev server perform the normal HTML transformation first and then exposes the transformed result to Rollup/your application as a normal JS module.

One caveat: if the HTML is ultimately inserted into a document at a different URL than the HTML entry's URL, there isn't a single relative URL that can be correct for both locations. In that case, root-relative URLs or an explicit <base href="..."> are safer than trying to preserve ./... references.

[ThinkingPlanely]

Yes, this is basically how I have it setup currently. But I want fix the one caveat that you mentioned by having Vite convert all references in the HTML to absolute when I call viteServer.transformIndexHtml. The resolveId hook isn't called when using this method so I'm not sure how I would go about this.

[chzaeem47]

Yes — I think the missing piece is that transformIndexHtml() isn't really designed as a generic "make every URL absolute" API, and resolveId isn't the hook you need here.

transformIndexHtml(url, html) uses the URL you pass as the HTML document's URL context. Vite's own HTML middleware does essentially the same thing:

html = await server.transformIndexHtml(url, html, req.originalUrl)

So for your virtual-module approach, I'd make the url you pass to transformIndexHtml() represent the final/public URL of the HTML being transformed, rather than the filesystem path or the virtual module URL.

For example:

const htmlUrl = `/pages/${name}/index.html`;

const transformed = await viteServer.transformIndexHtml(
  htmlUrl,
  html
);

Then, if your source contains:

<script type="module" src="./index.ts"></script>
<img src="./logo.svg">
<link rel="stylesheet" href="./style.css">

those references are interpreted relative to that HTML URL.

However, there's an important limitation: dev Vite does not generally rewrite every arbitrary relative URL into a root-absolute URL just because transformIndexHtml() was called. Vite normally keeps URLs compatible with the HTML document's base, while the module/asset requests themselves are resolved by Vite when the browser requests them. Vite's docs describe asset URLs as being resolved based on the project root during development.

If your actual requirement is:

<!-- source -->
<img src="./logo.svg">
<script type="module" src="./index.ts"></script>

<!-- desired string result -->
<img src="/pages/foo/logo.svg">
<script type="module" src="/pages/foo/index.ts">

then I'd handle this at the point where you generate the string rather than trying to make resolveId participate.

A simple approach is to normalize the URLs before calling transformIndexHtml():

const htmlUrl = `/pages/${name}/`;
const transformed = await viteServer.transformIndexHtml(
  htmlUrl,
  html
);

and make your imported HTML use URLs relative to a stable public root:

<script type="module" src="/pages/foo/index.ts"></script>
<img src="/pages/foo/logo.svg">

That is also consistent with Vite's documented development model: root-absolute asset URLs are resolved from the Vite project root.

If you specifically want to support arbitrary ./foo / ../foo references while embedding the HTML into another document, then I think the cleanest solution is a small HTML URL rewriter after transformIndexHtml():

const transformed = await viteServer.transformIndexHtml(
  htmlUrl,
  html
);

const absoluteHtml = rewriteRelativeUrls(
  transformed,
  htmlUrl
);

The key is that this should happen after Vite has done its HTML/module processing, so you're not replacing Vite's asset resolution logic; you're only changing the final representation from relative URLs to URLs rooted at the public HTML location.

So I wouldn't try to solve this through resolveId. resolveId is part of module resolution, while transformIndexHtml() is the HTML transformation API. The two solve different problems.