Natural Potato Magnet

    unplugin
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.1 • Public • Published

    unplugin

    NPM version

    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
    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 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.

    Hook Context

    Supported
    Hook Rollup Vite Webpack 4 Webpack 5 esbuild
    this.parse
    this.addWatchFile
    this.emitFile5
    this.getWatchFiles
    this.warn
    this.error
    1. Currently, this.emitFile only supports the EmittedAsset variant.

    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 esbuildPlugin = unplugin.esbuild

    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 esbuild
    >=3.16 ⚠️7
    1. Rollup supports nested plugins since v3.1.0. Plugin aurthor should ask users to a have a Rollup version of >=3.1.0 when using nested plugins. For singe plugin format, unplugin works for any versions of Rollup.
    2. Since esbuild does not have a built-in transform phase, the transform hook of 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 */ })
      ]
    })

    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' | 'esbuild'
    
      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
        },
        esbuild: {
          // change the filter of onResolve and onLoad
          onResolveFilter?: RegExp
          onLoadFilter?: RegExp
          // or you can completely replace the setup logic
          setup?: EsbuildPlugin['setup']
        }
      }
    })

    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

    License

    MIT License © 2021-PRESENT Nuxt Contrib

    Keywords

    none

    Install

    npm i unplugin

    DownloadsWeekly Downloads

    674,806

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    121 kB

    Total Files

    12

    Last publish

    Collaborators

    • antfu