how to customize `<script src` relative path transformation in `ViteDevServer` #13763

dislido · 2023-07-10T02:58:20Z

dislido
Jul 10, 2023

I'm using koa to build my node server, and using ViteDevServer in development mode. The main codes are as follows:

import Koa from 'koa';
import connect from 'koa2-connect'; // transform express middleware to koa middleware
import { createServer } from 'vite';
import renderMiddleware from './middlewares/render.js'; // render html templates

const app = new Koa();

app.use(renderMiddleware);

// ...other middlewares

if (process.env.HMR) {
  const vite = await createServer({
    server: { middlewareMode: true },
    appType: 'custom',
  });
  app.use(connect(vite.middlewares));
  app.use(async (ctx, next) => {
    await next();

    if (ctx.type === 'text/html') {
      // `renderMiddleware` has placed the HTML string in `ctx.body`
      ctx.body = await vite.transformIndexHtml(ctx.request.url, ctx.body);
    }
  });
}

app.listen(80);

My vite.config.ts:

export default defineConfig({
  build: {
    assetsDir: 'build',
    outDir: new URL('./static', import.meta.url).pathname,
    rollupOptions: {
      // html file path has no relation to url path
      input: {
        index: new URL('client/pages/index/index.html', import.meta.url).pathname, // localhost
        test: new URL('client/pages/test/index.html', import.meta.url).pathname, // localhost/test
      },
    },
  },
});

My html files:
renderSlot:${name}will be replaced in renderMiddleware

<!DOCTYPE html>
<html lang="zh-cn">
  <head>
    <title><!-- renderSlot:title --></title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width">
    <!-- renderSlot:head -->
    <script type="module" src="./index.tsx"></script>
  </head>
  <body>
    <!-- renderSlot:body -->
  </body>
</html>

When I run 'vite build', the <script type="module" src="./index.tsx"></script>will be transformed to <script type="module" crossorigin src="/build/index-{hash}.js"></script>, but it will keep src="./index.tsx" in ViteDevServer because vite can't get the html file path by the request url. Is there a way to tell ViteDevServer how to transform it?

dislido · 2023-07-10T08:36:00Z

dislido
Jul 10, 2023
Author

Now I am using this code as a workaround, manually transform it to an absolute path

ctx.body = htmlStr.replace(
  /<script ([^>]* |)src="([^"]+)"/g,
  (...args) => `<script ${args[1]}src="${path.resolve(path.parse(htmlFilePath).dir, args[2])}"`,
);

0 replies

ThinkingPlanely · 2026-08-27T19:23:17Z

ThinkingPlanely
Aug 27, 2026

I'm surprised that there doesn't seem to be a proper way to do this. @dislido did you find any other solution besides manually replacing the links? I also need this for my processed HTML import plugin.

0 replies

dislido · 2026-08-29T02:14:05Z

dislido
Aug 29, 2026
Author

@ThinkingPlanely Now I am using vite@8.2.2, I still have no way to deal with this. The only progress is that I have discovered that I can use an absolute path based on viteConfig.root in HTML to avoid additional manual replacements:

packages/server/index.ts

const vite = await createServer({
    root: path.resolve(projectRoot, './packages/client'),
    // ...

packages/client/pages/test/index.html

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

I still can't avoid manual replacement while using relative paths

0 replies

chzaeem47 · 2026-08-30T21:00:18Z

chzaeem47
Aug 30, 2026

I think the key issue is that transformIndexHtml() is being called with ctx.request.url, but Vite normally needs to know which HTML file that URL corresponds to in order to resolve relative URLs like ./index.tsx.

Since your HTML is generated by renderMiddleware rather than served directly from Vite, Vite has no way to infer that /test should be transformed using client/pages/test/index.html.

A cleaner workaround than regex-replacing the script tag is to pass Vite the HTML file path (or a URL that correctly maps to that file) when calling transformIndexHtml().

For example, if you already know the HTML file selected by renderMiddleware:

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

const transformed = await vite.transformIndexHtml(
  fileURLToPath(pathToFileURL(htmlFilePath)),
  html
);

ctx.type = 'text/html';
ctx.body = transformed;

However, if your rendered HTML contains application-specific placeholders and is not actually read from disk at that point, I'd recommend keeping the mapping between the request URL and the source HTML file in your render middleware:

const htmlFilePath = getHtmlFileForRequest(ctx.path);

let html = await fs.promises.readFile(htmlFilePath, 'utf8');

// Replace your renderSlot placeholders here
html = renderHtml(html, data);

// Give Vite the URL corresponding to the actual source HTML file
html = await vite.transformIndexHtml(
  ctx.path,
  html,
  htmlFilePath
);

ctx.type = 'text/html';
ctx.body = html;

The important part is that the transformation needs to be associated with the real HTML entry, not just the generated request URL.

Another approach, which I think is simpler for this project structure, is to make the paths absolute from Vite's root:

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

and configure:

const vite = await createServer({
  root: path.resolve(projectRoot, './packages/client'),
  server: {
    middlewareMode: true,
  },
  appType: 'custom',
});

Then Vite can resolve the module directly from its configured root without having to infer which physical HTML file /test came from.

So the underlying issue isn't really HMR itself — it's that your server is doing custom HTML rendering while Vite is being asked to perform an HTML transformation without knowing the source HTML entry. If you keep relative paths, you'll need to preserve/pass that HTML-file context somewhere in your rendering pipeline.

0 replies

Navigation Menu

Uh oh!

Uh oh!

how to customize `<script src` relative path transformation in `ViteDevServer` #13763

Uh oh!

{{title}}

Uh oh!

Replies: 4 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

Uh oh!

how to customize <script src relative path transformation in ViteDevServer #13763

Uh oh!

dislido Jul 10, 2023

Replies: 4 comments

Uh oh!

Uh oh!

dislido Jul 10, 2023 Author

Uh oh!

ThinkingPlanely Aug 27, 2026

Uh oh!

dislido Aug 29, 2026 Author

Uh oh!

chzaeem47 Aug 30, 2026

how to customize `<script src` relative path transformation in `ViteDevServer` #13763

dislido
Jul 10, 2023

dislido
Jul 10, 2023
Author

ThinkingPlanely
Aug 27, 2026

dislido
Aug 29, 2026
Author

chzaeem47
Aug 30, 2026