unimport

unimport

Unified utils for auto importing APIs in modules, used in nuxt and unplugin-auto-import

Features

• Auto import register APIs for Vite, Webpack or esbuild powered by unplugin
• TypeScript declaration file generation
• Auto import for custom APIs defined under specific directories
• Auto import for Vue template

Install

# npm
npm install unimport

# yarn
yarn add unimport

# pnpm
pnpm install unimport

Usage

Plugin Usage

Powered by unplugin, unimport provides a plugin interface for bundlers.

Vite / Rollup

// vite.config.js / rollup.config.js
import Unimport from 'unimport/unplugin'

export default {
  plugins: [
    Unimport.vite({ /* plugin options */ })
  ]
}

Webpack

// webpack.config.js
import Unimport from 'unimport/unplugin'

module.exports = {
  plugins: [
    Unimport.webpack({ /* plugin options */ })
  ]
}

Programmatic Usage

// ESM
import { createUnimport } from 'unimport'

// CommonJS
const { createUnimport } = require('unimport')

const { injectImports } = createUnimport({
  imports: [{ name: 'fooBar', from: 'test-id' }]
})

// { code: "import { fooBar } from 'test-id';console.log(fooBar())" }
console.log(injectImports('console.log(fooBar())'))

Configurations

Imports Item

Named import

imports: [
  { name: 'ref', from: 'vue' },
  { name: 'useState', as: 'useSignal', from: 'react' },
]

Will be injected as:

import { ref } from 'vue'
import { useState as useSignal } from 'react'

Default import

imports: [
  { name: 'default', as: '_', from: 'lodash' }
]

Will be injected as:

import _ from 'lodash'

Custom Presets

Presets are provided as a shorthand for declaring imports from the same package:

presets: [
  {
    from: 'vue',
    imports: [
      'ref',
      'reactive',
      // ...
    ]
  }
]

Will be equivalent as:

imports: [
  { name: 'ref', from: 'vue' },
  { name: 'reactive', from: 'vue' },
  // ...
]

Built-in Presets

unimport also provides some builtin presets for common libraries:

presets: [
  'vue',
  'pinia',
  'vue-i18n',
  // ...
]

You can check out src/presets for all the options available or refer to the type declaration.

Exports Auto Scan

Since unimport v0.7.0, we also support auto scanning the examples from a local installed package, for example:

presets: [
  {
    package: 'h3',
    ignore: ['isStream', /^[A-Z]/, /^[a-z]*$/, r => r.length > 8]
  }
]

This will be expanded into:

imports: [
  {
    from: 'h3',
    name: 'appendHeader',
  },
  {
    from: 'h3',
    name: 'appendHeaders',
  },
  {
    from: 'h3',
    name: 'appendResponseHeader',
  },
  // ...
]

The ignore option is used to filter out the exports, it can be a string, regex or a function that returns a boolean.

By default, the result is strongly cached by the version of the package. You can disable this by setting cache: false.

Type Declarations

Unimport.vite({
  dts: true // or a path to generated file
})

Directory Auto Import

dirs: [
  './composables/*'
]

Named exports for modules under ./composables/* will be registered for auto imports.

Opt-out Auto Import

You can opt-out auto-import for specific modules by adding a comment:

// @unimport-disable

It can be customized by setting commentsDisable:

Unimport.vite({
  commentsDisable: [
    '@unimport-disable',
    '@custom-imports-disable',
  ]
})

Acorn Parser

By default, unimport uses RegExp to detect unimport entries. In some cases, RegExp might not be able to detect all the entries (false positive & false negative).

We introduced a new AST-based parser powered by acorn, providing a more accurate result. The limitation is when using Acorn, it assumes all input code are valid and vanilla JavaScript code.

Unimport.vite({
  parser: 'acorn'
})

Vue Template Auto Import

In Vue's template, the usage of API is in a different context than plain modules. Thus some custom transformations are required. To enable it, set addons.vueTemplate to true:

Unimport.vite({
  addons: {
    vueTemplate: true
  }
})

Caveats

When auto-import a ref, inline operations won't be auto-unwrapped.

export const counter = ref(0)

<template>
  <!-- this is ok -->
  <div>{{ counter }}</div>

  <!-- counter here is a ref, this won't work, volar will throw -->
  <div>{{ counter + 1 }}</div>

  <!-- use this instead -->
  <div>{{ counter.value + 1 }}</div>
</template>

We recommend using Volar for type checking, which will help you to identify the misusage.

💻 Development

• Clone this repository
• Enable Corepack using corepack enable (use npm i -g corepack for Node.js < 16.10)
• Install dependencies using pnpm install
• Run interactive tests using pnpm dev

License

Made with 💛

Published under MIT License.

Changelog

3.7.0 (2023-12-22)

Bug Fixes

• vue-template: support auto import with $, close #298 (656756c)

Features

• introduce acorn as parser (#307) (be1dccc)