DOCSEARCHbyAlgolia
Submit Docs

vite-plugin-singlefile

repository·main·Indexed 22 days ago

https://github.com/richardtallent/vite-plugin-singlefile

A Vite build plugin that inlines all JavaScript and CSS resources directly into a single dist/index.html file. This allows web applications to be distributed as a single, portable HTML file that can be opened in a browser without a web server. Version 2.3.3.

Tokens
2.1K
Snippets
8
Records
14
Agent score
29%

What's inside vite-plugin-singlefile

  1. Understand the limitations of single-file builds

    main

    Core Concept: Single Entry Point

    This plugin is designed to create exactly one HTML file and no other files. It is not optimized for, and will not work well with, applications requiring multiple entry points (multiple HTML files).

    Local File Execution (file:///)

    When running the resulting HTML file locally (without a web server), certain behaviors apply:

    What works:

    • localStorage and experimental Persistent Storage APIs
    • FileSystem API
    • Relative requests for local files (e.g., resources from your public folder)
    • Requests for images/fonts from external websites
    • Requests to external APIs (requires { mode: 'no-cors' } in fetch)
    • SPA hash-based routing
    • WebXR

    What does NOT work:

    • SPA routing via Web History API
    • Cookies (as they rely on HTTP headers which don't exist for file:/// URIs)
    • WebXR Immersive Mode (not currently supported)
    • Worklets (not currently supported)
    • Sourcemaps (inlining happens after they are generated)

    Asset Caveats

    • Public Folder: Static resources in the public folder (like favicon) are NOT inlined by Vite or this plugin. However, the single HTML file can still reference them using relative paths.
    • SVGs: Direct inlining of SVGs is not supported by Vite or this plugin. Use a loader like vite-svg-loader or embed SVGs directly in your templates.

  3. Configure vite-plugin-singlefile options

    main

    You can pass a configuration object to viteSingleFile() to customize the inlining behavior.

    Available Options

    OptionDefaultDescription
    useRecommendedBuildConfigtrueAutomatically adjusts Vite configuration to allow assets to be combined into a single file.
    removeViteModuleLoaderfalseRemoves the Vite bundle-loading function from the final build. Recommended when inlining all bundles.
    inlinePattern[]An array of glob patterns (strings) to limit inlining to specific assets. Unmatched assets will trigger a warning.
    deleteInlinedFilestrueDeletes the original files after they are inlined. Set to false if you need to keep files for sourcemap uploads (e.g., to Sentry.io).
    overrideConfig{}A partial Rollup configuration object used to override the plugin's recommended defaults.

  5. Use vite-plugin-singlefile in your Vite configuration

    main

    Import viteSingleFile from vite-plugin-singlefile and add it to the plugins array in your vite.config.ts (or .js) file. This example shows usage with a Vue.js application.

    import { defineConfig } from "vite"
import vue from "@vitejs/plugin-vue"
import { viteSingleFile } from "vite-plugin-singlefile"

export default defineConfig({
	plugins: [vue(), viteSingleFile()],
})

  11. Configure vite-plugin-singlefile

    main

    The viteSingleFile plugin accepts a Config object to customize how assets are inlined and how the build is handled.

    Key configuration options:

    • useRecommendedBuildConfig (boolean, default: true): Automatically modifies the Vite build config (e.g., setting assetsInlineLimit to infinity, disabling cssCodeSplit, and setting base to ./) to ensure successful inlining.
    • removeViteModuleLoader (boolean, default: false): If true, removes the unused Vite module loader from the inlined script. This is safe because all JS is inlined.
    • inlinePattern (string[], default: []): A list of glob patterns. Only assets matching these patterns will be inlined. Assets not matching the pattern will be skipped and a note will be emitted.
    • deleteInlinedFiles (boolean, default: true): If true, deletes the original inlined JS and CSS files from the output bundle to prevent duplicate output.
    • overrideConfig (Partial<UserConfig>, default: {}): Allows you to pass a sparse object to override any specific Vite configuration settings after the recommended config has been applied.

  12. Manipulate HTML with replaceCss()

    main

    The replaceCss function is a utility used to inline a CSS file's content into an HTML string by replacing the corresponding <link href="..."> tag with a <style>...</style> tag containing the CSS. It automatically removes the @charset "UTF-8"; declaration from the inlined content.

    replaceCss(
  html: string, 
  scriptFilename: string, 
  scriptCode: string
): string