vite-plugin-utils

0.4.5 verified Mon Apr 27 auth: no javascript

vite-plugin-utils is a collection of opinionated utility functions for Vite plugin development. It provides constants, helper functions, and plugin sorting utilities to streamline plugin creation. Currently at version 0.4.5 with monthly releases, it focuses on reducing boilerplate for Vite plugin authors. Unlike general Vite utilities like unplugin or vite-plugin-inspect, this package offers specific sorted plugin handling and module-related constants. The package is ESM-only, designed for Vite 4+, and includes TypeScript declarations. Its lightweight API covers common patterns like virtual module IDs and plugin ordering.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /node_modules/vite-plugin-utils/index.js from /project/index.js not supported. ↓

cause Package is ESM-only. Using CommonJS require() to load it.

fix

Change to import statement: import { sortPlugin } from 'vite-plugin-utils/sort-plugin';

error Module not found: Can't resolve 'vite-plugin-utils' in '/project' ↓

cause Trying to import from package root without specifying subpath export.

fix

Import from a subpath: import { VIRTUAL_MODULE_PREFIX } from 'vite-plugin-utils/constant';

error Uncaught TypeError: vitePluginUtils is undefined ↓

cause Using default import from package root which exports nothing directly.

fix

Use named imports from subpath exports: import { sortPlugin } from 'vite-plugin-utils/sort-plugin';

Warnings

breaking Package is ESM-only. require() will throw ERR_REQUIRE_ESM. ↓

fix Use import syntax (ESM) or dynamic import() instead of require().

gotcha Subpath exports (e.g., 'constant', 'sort-plugin') must be accessed via full path 'vite-plugin-utils/constant', not from root. ↓

fix Use correct subpath import: import { VIRTUAL_MODULE_PREFIX } from 'vite-plugin-utils/constant'.

deprecated Some APIs in version <0.4.0 used different naming; check changelog for renames. ↓

fix Upgrade to 0.4.0+ and update imports to current subpath exports.

Install

npm install vite-plugin-utils

yarn add vite-plugin-utils

pnpm add vite-plugin-utils

Imports

resolveVitePluginUtils

wrong

const resolveVitePluginUtils = require('vite-plugin-utils')

correct

import { resolveVitePluginUtils } from 'vite-plugin-utils'

Package is ESM-only. CommonJS require will fail.

constant

wrong

import { VIRTUAL_MODULE_PREFIX } from 'vite-plugin-utils'

correct

import { VIRTUAL_MODULE_PREFIX } from 'vite-plugin-utils/constant'

Subpath export 'constant' is accessed via '/constant' suffix, not root.

sortPlugin

wrong

import { sortPlugin } from 'vite-plugin-utils'

correct

import { sortPlugin } from 'vite-plugin-utils/sort-plugin'

This utility is available under the '/sort-plugin' subpath.

Quickstart

Shows use of sortPlugin to order a custom plugin before vite:vue and VIRTUAL_MODULE_PREFIX constant for virtual module IDs in a Vite config.

import { defineConfig } from 'vite';
import { sortPlugin } from 'vite-plugin-utils/sort-plugin';
import { VIRTUAL_MODULE_PREFIX } from 'vite-plugin-utils/constant';

export default defineConfig({
  plugins: [
    sortPlugin({
      before: ['vite:vue'],
      plugin: myPlugin()
    })
  ],
  resolve: {
    alias: {
      [`${VIRTUAL_MODULE_PREFIX}my-module`]: '/path/to/my-module'
    }
  }
});

function myPlugin() {
  return {
    name: 'my-plugin',
    resolveId(id) {
      if (id.startsWith(VIRTUAL_MODULE_PREFIX)) return id;
    }
  };
}