Unified utils for auto importing APIs in modules, used in nuxt and unplugin-auto-import
- 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
# npm
npm install unimport
# yarn
yarn add unimport
# pnpm
pnpm install unimport
Powered by unplugin, unimport
provides a plugin interface for bundlers.
// vite.config.js / rollup.config.js
import Unimport from 'unimport/unplugin'
export default {
plugins: [
Unimport.vite({ /* plugin options */ })
]
}
// webpack.config.js
import Unimport from 'unimport/unplugin'
module.exports = {
plugins: [
Unimport.webpack({ /* plugin options */ })
]
}
// 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())'))
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'
imports: [
{ name: 'default', as: '_', from: 'lodash' }
]
Will be injected as:
import _ from 'lodash'
imports: [
{ name: '*', as: '_', from: 'lodash' }
]
Will be injected as:
import * as _ from 'lodash'
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' },
// ...
]
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.
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
.
Unimport.vite({
dts: true // or a path to generated file
})
dirs: [
'./composables/*'
]
Named exports for modules under ./composables/*
will be registered for auto imports.
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',
]
})
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'
})
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
}
})
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.
- Clone this repository
- Enable Corepack using
corepack enable
(usenpm i -g corepack
for Node.js < 16.10) - Install dependencies using
pnpm install
- Run interactive tests using
pnpm dev
Made with ๐
Published under MIT License.