npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

unplugin-test

v2.3.0

Published

Unified plugin system for build tools

Downloads

10

Readme

unplugin

npm version npm downloads License

Unified plugin system for build tools.

Currently supports:

Hooks

unplugin extends the excellent Rollup plugin API as the unified plugin interface and provides a compatible layer base on the build tools used with.

Supported

| Hook | Rollup | Vite | Webpack 4 | Webpack 5 | esbuild | Rspack | Farm | | ----------------------------------------------------------------------- | :-------------: | :--: | :-------: | :-------: | :-------------: | :----: | :--: | | enforce | ❌ 1 | ✅ | ✅ | ✅ | ❌ 1 | ✅ | ✅ | | buildStart | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | resolveId | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | | loadInclude2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | load | ✅ | ✅ | ✅ | ✅ | ✅ 3 | ✅ | ✅ | | transformInclude2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | transform | ✅ | ✅ | ✅ | ✅ | ✅ 3 | ✅ | ✅ | | watchChange | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | | buildEnd | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | writeBundle4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

  1. Rollup and esbuild do not support using enforce to control the order of plugins. Users need to maintain the order manually.
  2. Webpack's id filter is outside of loader logic; an additional hook is needed for better perf on Webpack. In Rollup and Vite, this hook has been polyfilled to match the behaviors. See for the following usage examples.
  3. Although esbuild can handle both JavaScript and CSS and many other file formats, you can only return JavaScript in load and transform results.
  4. Currently, writeBundle is only serves as a hook for the timing. It doesn't pass any arguments.

Warning: The Rspack support is experimental. Future changes to Rspack integrations might not follow semver, please pin unplugin in your dependency when using. It's not recommended to use in production..

Hook Context

Supported

| Hook | Rollup | Vite | Webpack 4 | Webpack 5 | esbuild | Rspack | Farm | | -------------------------------------------------------------------------- | :----: | :--: | :-------: | :-------: | :-----: | :----: | :--: | | this.parse | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | this.addWatchFile | ✅ | ✅ | ✅6 | ✅ | ✅7 | ❌ | ✅ | | this.emitFile5 | ✅ | ✅ | ✅6 | ✅ | ✅ | ✅ | ✅ | | this.getWatchFiles | ✅ | ✅ | ✅6 | ✅ | ✅7 | ❌ | ✅ | | this.warn | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | this.error | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

  1. Currently, this.emitFile only supports the EmittedAsset variant.
  2. Currently, in Webpack, this.addWatchFile, this.emitFile, and this.getWatchFiles are not supported within resolveId hooks.
  3. Currently, in esbuild, this.addWatchFile and this.getWatchFiles are supported only within resolveId, load, and transform hooks; and this.getWatchFiles returns an array of only the files explicitly watched via this.addWatchFile during the same resolve step (resolveId hook) or load step (load and transform hooks).

Usage

import { createUnplugin } from 'unplugin'

export const unplugin = createUnplugin((options: UserOptions) => {
  return {
    name: 'unplugin-prefixed-name',
    // webpack's id filter is outside of loader logic,
    // an additional hook is needed for better perf on webpack
    transformInclude(id) {
      return id.endsWith('.vue')
    },
    // just like rollup transform
    transform(code) {
      return code.replace(/<template>/, '<template><div>Injected</div>')
    },
    // more hooks coming
  }
})

export const vitePlugin = unplugin.vite
export const rollupPlugin = unplugin.rollup
export const webpackPlugin = unplugin.webpack
export const rspackPlugin = unplugin.rspack
export const esbuildPlugin = unplugin.esbuild
export const farmPlugin = unplugin.farm

Nested Plugins

Since v0.10.0, unplugin supports constructing multiple nested plugins to behave like a single one. For example:

Supported

| Rollup | Vite | Webpack 4 | Webpack 5 | Rspack | esbuild | Farm | | :--------------------: | :--: | :-------: | :-------: | :----: | :------------: | :--: | | ✅ >=3.16 | ✅ | ✅ | ✅ | ✅ | ⚠️7 | ✅ |

  1. Rollup supports nested plugins since v3.1.0. Plugin author should ask users to have a Rollup version of >=3.1.0 when using nested plugins. For single plugin format, unplugin works for any version of Rollup.
  2. Since esbuild does not have a built-in transform phase, the transform hook of the nested plugin will not work on esbuild yet. Other hooks like load or resolveId work fine. We will try to find a way to support it in the future.
Usage
import { createUnplugin } from 'unplugin'

export const unplugin = createUnplugin((options: UserOptions) => {
  return [
    {
      name: 'plugin-a',
      transform(code) {
        // ...
      },
    },
    {
      name: 'plugin-b',
      resolveId(id) {
        // ...
      },
    },
  ]
})

Plugin Installation

Vite
// vite.config.ts
import UnpluginFeature from './unplugin-feature'

export default {
  plugins: [
    UnpluginFeature.vite({ /* options */ }),
  ],
}
Rollup
// rollup.config.js
import UnpluginFeature from './unplugin-feature'

export default {
  plugins: [
    UnpluginFeature.rollup({ /* options */ }),
  ],
}
Webpack
// webpack.config.js
module.exports = {
  plugins: [
    require('./unplugin-feature').webpack({ /* options */ }),
  ],
}
esbuild
// esbuild.config.js
import { build } from 'esbuild'

build({
  plugins: [
    require('./unplugin-feature').esbuild({ /* options */ }),
  ],
})
Rspack
// rspack.config.js
module.exports = {
  plugins: [
    require('./unplugin-feature').rspack({ /* options */ }),
  ],
}
Farm
// farm.config.ts
import UnpluginFeature from './unplugin-feature'

module.exports = {
  plugins: [
    require('./unplugin-feature').farm({ /* options */ }),
  ],
}

Framework-specific Logic

While unplugin provides compatible layers for some hooks, the functionality of it is limited to the common subset of the build's plugins capability. For more advanced framework-specific usages, unplugin provides an escape hatch for that.

export const unplugin = createUnplugin((options: UserOptions, meta) => {
  console.log(meta.framework) // 'vite' | 'rollup' | 'webpack' | 'rspack' | 'esbuild' | 'farm'

  return {
    // Common unplugin hooks
    name: 'unplugin-prefixed-name',
    transformInclude(id) { /* ... */ },
    transform(code) { /* ... */ },

    // Framework specific hooks
    vite: {
      // Vite plugin
      configureServer(server) {
        // configure Vite server
      },
      // ...
    },
    rollup: {
      // Rollup plugin
    },
    webpack(compiler) {
      // Configure Webpack compiler
    },
    rspack(compiler) {
      // Configure Rspack compiler
    },
    esbuild: {
      // Change the filter of onResolve and onLoad
      // onResolveFilter?: RegExp,
      // onLoadFilter?: RegExp,

      // Tell esbuild how to interpret the contents. By default unplugin tries to guess the loader
      // from file extension (eg: .js -> "js", .jsx -> 'jsx')
      // loader?: (Loader | (code: string, id: string) => Loader)

      // Read and/or modify build.initialOptions
      // [https://esbuild.github.io/plugins/#build-options]
      // config?: (initialOptions: BuildOptions) => void

      // Or you can completely replace the setup logic
      // setup?: EsbuildPlugin.setup,
    },
    farm: {
      config(config) {
        // Configure Farm config
      },
      configureDevServer(server) {
        // Configure Farm dev server
      },
    }
  }
})

Creating platform specific plugins

The package exports a set of functions in place of createUnplugin that allow for the creation of plugins for specific bundlers. Each of the function takes the same generic factory argument as createUnplugin.

import {
  createEsbuildPlugin,
  createFarmPlugin,
  createRollupPlugin,
  createRspackPlugin,
  createVitePlugin,
  createWebpackPlugin,
} from 'unplugin'

const vitePlugin = createVitePlugin({ /* options */ })
const rollupPlugin = createRollupPlugin({ /* options */ })
const esbuildPlugin = createEsbuildPlugin({ /* options */ })
const webpackPlugin = createWebpackPlugin({ /* options */ })
const rspackPlugin = createRspackPlugin({ /* options */ })
const farmPlugin = createFarmPlugin({ /* options */ })

Conventions

  • Plugins powered by unplugin should have a clear name with unplugin- prefix.

  • Include unplugin keyword in package.json.

  • To provide better DX, packages could export 2 kinds of entry points:

    • Default export: the returned value of createUnplugin function

      import UnpluginFeature from 'unplugin-feature'
    • Subpath exports: properties of the returned value of createUnplugin function for each framework users

      import VitePlugin from 'unplugin-feature/vite'
    • Refer to unplugin-starter for more details about this setup.

Starter Templates

Community Showcases

We have started a GitHub organization to host and collaborate on popular unplugin plugins: github.com/unplugin. You can go there to find more plugins or even join us with your own plugins!

License

MIT License © 2021-PRESENT Nuxt Contrib