Home

Awesome

vite-plugin-singlefile

This Vite build plugin allows you to inline all JavaScript and CSS resources directly into the final dist/index.html file. By doing this, your entire web app can be embedded and distributed as a single HTML file.

Why?

Bundling your entire site into one file isn't recommended for most situations.

In particular, this is not a good idea, performance-wise, for hosting a site on a normal web server.

However, this can be very handy for offline web applications-- apps bundled into a single HTML file that you can double-click and open directly in your web browser, no server needed. This might include utilities, expert system tools, documentation, demos, and other situations where you want the full power of a web browser, without the need for a Cordova or Electron wrapper or the pain of normal application installation.

This is a single file plugin. As in, it creates one HTML file and no other files. Hence the name. So, this either will not work or will not be optimized for apps that require multiple "entry points" (HTML files). Please see issue #51 for details. Issues opened requesting multiple entry points will be closed as wontfix.

What does work when running an HTML file locally

Local HTML files are now for most purposes considered to be a "secure context" and thus now have far more capabilities than when this project started, which is good!

You can use:

I've only tested some of the above in Chromium-based browsers. YMMV for WebKit and other browser engines. Some may require explicit user permission.

What doesn't work

Installation

npm install vite-plugin-singlefile --save-dev

or

yarn add vite-plugin-singlefile --dev

How do I use it?

Here's an example vite.config.ts file using this plugin for a Vue.js app:

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

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

Config

You can pass a configuration object to modify how this plugin works. The options are described below:

useRecommendedBuildConfig

Defaults to true. This plugin will automatically adjust your vite configuration to allow assets to be combined into a single file. To disable this:

viteSingleFile({ useRecommendedBuildConfig: false })

Refer to the _useRecommendedBuildConfig function in the index.ts file of this repository to see the recommended configuration.

removeViteModuleLoader

Defaults to false. Vite includes a function in your build to load other bundles. Since we're inlining all bundles, you can use this option to have the bundle-loading function removed from your final build:

viteSingleFile({ removeViteModuleLoader: true })

inlinePattern

Defaults to [], which will inline all recognized JavaScript and CSS assets. You can provide a string array of "glob" patterns to limit the inlining to certain assets. Any assets missed by your patterns will generate a warning (same as any unrecognized assets).

deleteInlinedFiles

Defaults to true, which deletes all inlined files that were inlined. A use case for turning this to false would be if you would like sourcemaps to be generated so you can upload them to an error tracking platform like Sentry.io.

Caveats

Contributing

License

MIT