vite-plugin-src-update

vite-plugin-src-update is a Vite plugin that automatically updates a template file with development or production script tags for your project assets, ensuring the correct scripts are loaded depending on your build environment. It supports multiple templating languages, CDN-helper output, dev-server HMR injection, and custom template file paths.

Compatible with Vite 5, 6, 7 and 8 (Node.js ^20.19.0 || >=22.12.0).

Installation

npm install vite-plugin-src-update --save-dev

Usage

Import the plugin in your vite.config.js:

import vitePluginSrcUpdate from 'vite-plugin-src-update';

export default {
  plugins: [
    vitePluginSrcUpdate({
      templateFilePath: 'path/to/template.html',
      outDir: 'path/to/outDir',
      input: ["src/entrypoints/example.js", "src/styles/example.css"],
      cdn: false
    })
  ]
}

Options

• templateFilePath: Required -- Path to the template file.
• outDir: The directory where the bundled scripts are outputted. If you don't specify outDir, it will use build.outDir.
• input: Array of entry points for the scripts and styles to be included in the template. If you don't specify input, it will use the rolldownOptions/rollupOptions input.
• cdn: Whether to wrap built asset paths in a {{cdn '...'}} helper (e.g. BigCommerce Stencil's Handlebars CDN helper) so URLs are rewritten to the platform's CDN at render time. Defaults to false.
• injectClient: Whether to inject Vite's HMR client (@vite/client) in dev mode so backend-served pages get hot module replacement. Defaults to true.
• verbose: Log additional diagnostic information. Defaults to false.
• dryRun: Compute the output without writing the template file. Defaults to false.
• commentTemplates: Per-extension formatters for the auto-generated header comment. Defaults cover .html, .liquid, .hbs and .cshtml.

You can also pass an array of objects to update multiple template files.

export default {
  plugins: [
    vitePluginSrcUpdate([
      {
        templateFilePath: 'path/to/template.html',
        input: ["src/entrypoints/example.js"],
      },
      {
        templateFilePath: 'path/to/another/template.html',
        outDir: 'path/to/outDir',
        input: ["src/styles/example.css"],
      },
    ]),
  ]
}

How it works

The plugin rewrites your template file with the correct asset tags depending on how Vite is invoked:

• Dev (vite / vite dev) — once the dev server is listening, it writes <script type="module"> tags pointing at the running dev server. With injectClient enabled (the default), Vite's HMR client (@vite/client) is injected first, so backend-served pages get hot module replacement:

<!-- IMPORTANT: This component is automatically generated by vite-plugin-src-update.
Do not attempt to modify this file directly, as any changes will be overwritten by the next build. -->
<script type="module" src="http://localhost:5173/@vite/client"></script>
<script type="module" src="http://localhost:5173/src/entrypoints/main.js"></script>

• Build (vite build) — after the bundle is written, it emits <script type="module"> tags for entry chunks and <link rel="stylesheet"> tags for CSS assets, using the hashed output filenames prefixed with outDir (and wrapped in {{cdn '...'}} when cdn is enabled):

<!-- IMPORTANT: This component is automatically generated by vite-plugin-src-update.
Do not attempt to modify this file directly, as any changes will be overwritten by the next build. -->
<script type="module" src="vite-build/main.bundle.8WQytZJj.js"></script>
<link rel="stylesheet" href="vite-build/main.min.DXYuBBGC.css">

Each file begins with an auto-generated header comment, formatted for the template's extension (see commentTemplates). The template is only rewritten when its contents actually change, so backend file-watchers (BigCommerce Stencil CLI, dotnet watch, Shopify CLI, etc.) won't trigger needless reloads on no-op builds.

What kinds of projects is this for?

This plugin shines whenever Vite isn't the thing serving your HTML — i.e. a separate platform or backend renders the markup and just needs the right <script>/<link> tags pointing at your Vite assets. Because it writes a ready-to-include snippet (dev-server URLs while developing, hashed file paths after a build) directly into a template file, the host platform doesn't need to read a manifest or run any Vite integration at request time.

Typical use cases include:

• E-commerce themes — Shopify (Liquid), BigCommerce Stencil (Handlebars), and similar platforms where storefront templates are rendered server-side. The cdn option emits a {{cdn '...'}} helper for platforms that serve assets through their own CDN.
• Server-rendered .NET — classic ASP.NET (non-Core) MVC / Web Forms .cshtml Razor views, where there's no first-party Vite tag helper to lean on.
• Other templating engines — Handlebars, Mustache, and anything else where you'd otherwise hand-maintain the asset tags. Add your own extension to commentTemplates to format the generated header comment for it.
• Any multi-target build — pass an array of configs to keep several template files (across different platforms) in sync from a single Vite build.

Out of the box, the auto-generated header comment is formatted for .html, .liquid, .hbs and .cshtml, and you can extend it to any other extension.

Publishing

This package uses a GitHub Action to automatically publish to npm when changes are pushed to the main branch. The workflow:

1. Checks out the code
2. Sets up Node.js 24.x
3. Upgrades npm (OIDC trusted publishing requires npm >= 11.5.1)
4. Installs dependencies
5. Checks whether the package version already exists on npm
6. Builds and publishes through prepublishOnly when the version is new

Publishing uses npm Trusted Publishing (OIDC) — no long-lived NPM_TOKEN is stored. The workflow authenticates with a short-lived, job-specific credential, so there is nothing to rotate. To set this up, add a Trusted Publisher in the package's settings on npmjs.com pointing at this repository and the publish.yml workflow, and keep the id-token: write permission in the workflow. Publishes also include provenance automatically.

MIT License

Copyright (c) 2025 Julian Bo Bendtsen

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.