Git Product home page Git Product logo

unplugin's Introduction

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

unplugin's People

Contributors

antfu avatar renovate[bot] avatar sxzz avatar jwr1 avatar lforst avatar demivan avatar m0ksem avatar nozomuikuta avatar tropicalraisel avatar dunqing avatar vladanpaunovic avatar yfwz100 avatar talljack avatar zenotsai avatar zenquan avatar patrickchen928 avatar hyrious avatar kricsleo avatar lxy-yz avatar zhiyuanzmj avatar zouhangwithsweet avatar jaxonly avatar ssssota avatar pd4d10 avatar edimitchel avatar linghanchujian avatar jpsc avatar userquin avatar ianvs avatar jserfeng avatar

Stargazers

Roman avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.