zheeeng / vite-plugin-plain-text

A Vite plugin transforms the rule-matched file as plain text.

vite-plugin-plain-text

A Vite plugin that transforms matched files into plain text.

Installation

pnpm i -D vite-plugin-plain-text (or npm/yarn)

Usage Example

Assume we are going to transform these files:

1. The project's LICENSE file
2. Textbox
3. .glsl file

into plain text.

// vite.config.(t|j)s

import { defineConfig } from 'vite';

import plainText from 'vite-plugin-plain-text';

export default defineConfig({
  plugins: [
    // passing regular expression or glob matcher
    plainText([/\/LICENSE$/, '**/*.text', /\.glsl$/]),
  ],
});

// component.js

import { plainText as LICENSE } from '../LICENSE'
import { plainText as Lorem } from '../lorem-ipsum.text'
import { plainText as Siren } from '../siren.glsl'

console.log(LICENSE)
console.log(Lorem)
console.log(Siren)

Advanced Usage

Options Reference

type PlainTextOptions = {
  namedExport?: string | false,
  dtsAutoGen?: boolean,
  distAutoClean?: boolean,
}

Enable Default Export

Use the plainTextOptions.namedExport option to configure the named exported variable. To enable the default export, pass false, '', or undefined.

// vite.config.(t|j)s

import { defineConfig } from 'vite';
import plainText from 'vite-plugin-plain-text';

export default defineConfig({
  plugins: [
    plainText(
      [/\/LICENSE$/, '**/*.text', /\.glsl$/],
      { namedExport: false },
    ),
  ],
});

// component.js

import LICENSE from '../LICENSE'
import Lorem from '../lorem-ipsum.text'
import Siren from '../siren.glsl'

console.log(LICENSE)
console.log(Lorem)
console.log(Siren)

Type Safety

Adding Module Declarations Manually

// vite-env.d.ts
declare module '*/LICENSE' {
    export const plainText: string
}
declare module '*.text' {
    export const plainText: string
}
declare module '*.glsl' {
    export const plainText: string
}

Generate the declaration automatically

1. plainTextOptions.dtsAutoGen generates .dts files for matched files.
2. plainTextOptions.dtsAutoClean cleans up these .dts files after the vite plugin starts up each time.

import { defineConfig } from 'vite';
import plainText from 'vite-plugin-plain-text';

export default defineConfig({
  plugins: [
    plainText(
      [/\/LICENSE$/, '**/*.text', /\.glsl$/],
      { namedExport: false, dtsAutoGen: true, distAutoClean: true },
    ),
  ],
});

License

MIT

Alternative

Virtual asset Loader: vite-plugin-virtual-plain-text

vite-plugin-plain-text's Issues

Package exports { default }

The type defs and the docs asks to do this in vite.config.ts:

import { defineConfig } from "vite";
import plainText from "vite-plugin-plain-text";

export default defineConfig({
  plugins: [
    plainText(/\.glsl$/),
  ],
});

but this is what works for me:

import { defineConfig } from "vite";
import plainText from "vite-plugin-plain-text";

export default defineConfig({
  plugins: [
    // @ts-ignore
    plainText.default(/\.glsl$/), // <--
  ],
});

There seems to be a minor issue in your transpilation/commonjs/build pipeline :)

Consider returning text in a default export

This will be very convenient to migrate off the webpack's raw-loader for specific file types, which always return a default export from them.

Before

import { plainText } from 'some-file';

After

import plainText from 'some-file';

Sourcemap is likely to be incorrect warning

I enabled source maps in my Vite build config.

export default defineConfig({
  plugins: [
    plainText(/\,hbs$/),
  ],
  
  build: {
    sourcemap: true,
  },
})

When I do a build, I get the following error

Sourcemap is likely to be incorrect: a plugin (plain text) was used to transform files, but didn't generate a sourcemap for the transformation. Consult the plugin documentation for help