vite-plugin-singlefile

2.3.3 verified Sat Apr 25 auth: no javascript

Vite plugin for inlining all JavaScript and CSS resources into a single HTML file. Version 2.3.3 is the latest stable release. The plugin is actively maintained with frequent updates. It differentiates from other inline plugins by focusing on producing a single index.html with no other output files, supporting Vite 5, 6, 7, and 8. It is specifically designed for offline web applications (single-file apps) and not recommended for server-hosted sites. The plugin automatically adjusts Vite build config for asset inlining and includes options to remove Vite's module loader and delete inlined files.

Common errors

error Error: The plugin 'vite-plugin-singlefile' doesn't support multiple HTML files as entry points. ↓

cause Vite configuration has multiple inputs (e.g., rollupOptions.input with more than one HTML file).

fix

Ensure only one entry HTML is specified, e.g., rollupOptions.input: 'index.html'.

error TypeError: viteSingleFile is not a function ↓

cause Using CommonJS require() on an ESM-only package.

fix

Switch to import { viteSingleFile } from 'vite-plugin-singlefile' in an ESM context.

error [vite] RollupError: Could not resolve 'vite-plugin-singlefile' (required by ...) ↓

cause Package is not installed or peer dependencies (vite, rollup) are missing or mismatched.

fix

Run npm install vite-plugin-singlefile and ensure vite and rollup meet version requirements.

error Error: InlinePattern matched no assets. All assets will be inlined. ↓

cause inlinePattern is set to a pattern that doesn't match any output files.

fix

Check the pattern syntax (glob) and verify the output file names. Use [] to inline all assets.

Warnings

gotcha Multiple entry points are not supported. The plugin only works with a single HTML entry point. See issue #51. ↓

fix Ensure your Vite config has only one input HTML file. Use vite-plugin-singlefile only for single-page applications.

breaking v2.x requires Node.js >18.0.0. Node 16 is no longer supported. ↓

fix Upgrade Node.js to version 18 or later.

deprecated useRecommendedBuildConfig option is deprecated as of v2.3.0. The plugin now auto-applies recommended config. ↓

fix Remove useRecommendedBuildConfig from options or set to true explicitly.

gotcha Sourcemaps are not supported because inlining happens after sourcemap generation. They will be missing from the final output. ↓

fix Disable sourcemaps in Vite config: build.sourcemap: false to avoid confusion.

gotcha The plugin deletes inlined files by default (deleteInlinedFiles: true). This removes the original JS/CSS files from the output directory. ↓

fix Set deleteInlinedFiles: false if you want to keep the original files alongside the inline HTML.

Install

npm install vite-plugin-singlefile

yarn add vite-plugin-singlefile

pnpm add vite-plugin-singlefile

Imports

viteSingleFile

wrong

const viteSingleFile = require('vite-plugin-singlefile')

correct

import { viteSingleFile } from 'vite-plugin-singlefile'

ESM-only package. Named export. CommonJS require will fail.

InlineConfig

wrong

import { InlineConfig } from 'vite-plugin-singlefile'

correct

import type { InlineConfig } from 'vite-plugin-singlefile'

Type export only; not a runtime value. Use 'import type' or 'import { type InlineConfig }'.

default

wrong

const viteSingleFile = require('vite-plugin-singlefile').default

correct

import viteSingleFile from 'vite-plugin-singlefile'

Default export is available but named export is preferred. CommonJS require is not supported.

Quickstart

Basic configuration for a Vue.js app to inline all JS and CSS into a single HTML file.

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

export default defineConfig({
  plugins: [vue(), viteSingleFile({
    useRecommendedBuildConfig: true,
    removeViteModuleLoader: false,
    inlinePattern: [],
    deleteInlinedFiles: true
  })],
});