vite-string-plugin

2.0.3 verified Mon Apr 27 auth: no javascript

A zero-dependency Vite plugin that allows importing files (SVG, MD, XML, TXT, or custom extensions) as raw strings at build time. Current stable version is 2.0.3 as of April 2025, requiring Vite >= 6.3.0 (or compatible rolldown-vite) due to hook filter API usage introduced in v2.0.0. It is more lightweight than generic file-loading plugins like rollup-plugin-string or vite-plugin-raw, but limited to string output. TypeScript type declarations are provided via a separate types entry point for automatic module augmentation of default file extensions.

Common errors

error TypeError: vite-string-plugin is not a function ↓

cause Attempting to call require('vite-string-plugin') which returns an ESM module; it does not have a default export.

fix

Use import { stringPlugin } from 'vite-string-plugin' instead of const stringPlugin = require('vite-string-plugin').

error Plugin vite-string-plugin: filter is not a function ↓

cause Vite version < 6.3.0 does not support the hook filter API used by plugin v2.

fix

Upgrade Vite to >=6.3.0 or use vite-string-plugin@1.0.5.

error TypeScript error: Cannot find module './foo.svg' or its corresponding type declarations. ↓

cause Missing type augmentation for the imported file extension.

fix

Add "types": ["vite-string-plugin/types"] to tsconfig.json or create a .d.ts file with declare module statements.

Warnings

breaking vite-string-plugin@2.0.0 requires Vite >= 6.3.0 (or rolldown-vite equivalent) due to hook filter API usage. Older Vite versions will fail to load the plugin. ↓

fix Upgrade Vite to 6.3.0 or later, or use vite-string-plugin@1.x (v1.0.5) with Vite < 6.3.0.

gotcha Files imported via stringPlugin are not hot-reloaded in dev mode? (check if HMR works) ↓

fix Ensure the plugin is added to the Vite plugins array; HMR should work automatically for files matching the pattern. If not, try appending a query parameter like ?raw.

deprecated The 'match' option default covers only .svg, .md, .xml, .txt. Customizing match may be needed for other extensions like .graphql or .html. The plugin does not handle query parameters like ?raw (but can be combined with Vite's ?raw). ↓

fix Set match to a broader regex or use Vite's built-in ?raw query for specific files.

gotcha TypeScript type augmentation only applies to default extensions (.svg, .md, .xml, .txt). For custom extensions, you must add your own declare module statements. ↓

fix Add ambient type declarations for each custom extension as shown in the README.

Install

npm install vite-string-plugin

yarn add vite-string-plugin

pnpm add vite-string-plugin

Imports

stringPlugin

wrong

const { stringPlugin } = require('vite-string-plugin')

correct

import { stringPlugin } from 'vite-string-plugin'

ESM-only package, no CommonJS support. Named export, not default.

types

wrong

import './vite-string-plugin/types'

correct

/// <reference types="vite-string-plugin/types" />
or in tsconfig.json: "types": ["vite-string-plugin/types"]

Type augmentation is done via types entry; do not import it as a module.

default import of file
wrong
```
import { foo } from './foo.svg'; const data = require('./foo.svg')
```
correct
```
import foo from './foo.svg'
```
Files are exported as default string export; named or require will fail in ESM context.

Quickstart

Sets up the plugin to load .svg files as strings and then imports one in a TypeScript module.

// vite.config.js
import { defineConfig } from 'vite';
import { stringPlugin } from 'vite-string-plugin';

export default defineConfig({
  plugins: [
    stringPlugin({
      match: /\.(svg|md|xml|txt)$/i
    }),
  ],
});

// src/example.ts
import svgContent from './icon.svg?raw'; // works only if match includes .svg
console.log(svgContent); // string of the file content