Vite Plugin Inline Source

4.1.0 verified Mon Apr 27 auth: no javascript

A Vite plugin (v4.1.0) that inlines external file contents into HTML elements with the `inline-source` attribute. Actively maintained, with regular releases. Supports Vite 5, 6, and 7. Unlike `vite-plugin-singlefile`, this allows selective inlining per tag. Features include SVG optimization via SVGO, CSS optimization via CSSO, JS minification via Terser, and Sass compilation. Customization options for the inline attribute trigger, replacement tags, and optimization settings.

Common errors

error Cannot find module 'vite-plugin-inline-source' or its corresponding type declarations. ↓

cause Package may not be installed, or TypeScript is not resolving the module correctly.

fix

Install the package: npm install --save-dev vite-plugin-inline-source. For TypeScript, ensure node module resolution is configured.

error 'require' is not defined in ES module scope; you can use import instead. ↓

cause Using CommonJS `require` in an ES module context. The plugin is ESM-only.

fix

Use import inlineSource from 'vite-plugin-inline-source'.

error Vite build fails with 'Error: Inline source not found: path/to/file.css' ↓

cause The `src` attribute in HTML points to a file that does not exist or is not resolvable by Vite.

fix

Verify the file path relative to the project root. Ensure the file is included in Vite's build scope.

error TypeError: inlineSource is not a function ↓

cause The import is incorrect, e.g., default import used as if exported as an object.

fix

Use import inlineSource from 'vite-plugin-inline-source' (default import).

Warnings

breaking v4.0.0 dropped support for Vite versions older than 5.x. Existing v3 projects must upgrade Vite to 5.x or newer. ↓

fix Update Vite to 5.x, 6.x, or 7.x in your package.json.

breaking v4.0.0 upgraded SVGO from v3 to v4. SVGO v4 includes breaking changes. Refer to SVGO migration guide. ↓

fix Review https://svgo.dev/docs/migrations/migration-from-v3-to-v4/ and update SVGO options accordingly.

breaking v3.0.0 dropped support for Node.js 18. Existing projects on Node 18 must upgrade. ↓

fix Upgrade Node.js to version 20 or later.

gotcha The plugin only inlines assets during the build (production) phase, not in dev mode. This is a common misunderstanding. ↓

fix Use `npm run build` and serve the output; the plugin does not affect `vite dev`.

deprecated Node.js 18 support was dropped in v3.0.0. Using Node 18 with v3+ will cause errors. ↓

fix Upgrade Node.js to 20+ or pin to vite-plugin-inline-source@2.x (which supports Node 18).

Install

npm install vite-plugin-inline-source

yarn add vite-plugin-inline-source

pnpm add vite-plugin-inline-source

Imports

default

wrong

const inlineSource = require('vite-plugin-inline-source')

correct

import inlineSource from 'vite-plugin-inline-source'

Default import only; no named exports. CommonJS require fails in ESM-only contexts.

InlineSourceOptions

wrong

import { InlineSourceOptions } from 'vite-plugin-inline-source'

correct

import type { InlineSourceOptions } from 'vite-plugin-inline-source'

TypeScript type import only; not a runtime export. Use `import type` to avoid errors.

Plugin
```
import inlineSource from 'vite-plugin-inline-source'
```
The plugin is used as a function that returns a Vite Plugin object. No separate Plugin symbol.

Quickstart

Configures the vite-plugin-inline-source plugin with default options in a Vite config file.

// vite.config.ts
import { defineConfig } from 'vite';
import inlineSource from 'vite-plugin-inline-source';

export default defineConfig({
  plugins: [
    inlineSource({
      // customize inline attribute (default: 'inline-source')
      customAttribute: 'inline-source',
      // tags whose contents are replaced entirely (default: ['svg', 'math'])
      replaceTags: ['svg', 'math'],
      // enable SVG optimization (default: true)
      optimizeSvgs: true,
      // enable CSS optimization (default: false)
      optimizeCss: false,
      // enable JS minification (default: false)
      optimizeJs: false,
      // enable Sass compilation (default: false)
      compileSass: false
    })
  ]
});