随笔,告别手动引入依赖:unplugin-auto-import 插件助你提升编码体验(内附实现原理)

模块化已经是现代 Web 开发必不可少的开发方式,频繁引入依赖包是一个常见的操作。但是,手动引入依赖包往往繁琐,尤其是当依赖包数量较多时,会显著降低开发效率。

unplugin-auto-import 插件,可以帮助我们在项目中,自动导入常用的使用的第三方库的 API,就可以方便我们开发,提升开发效率。

使用效果

以 Vue 为例,在没有使用自动导入前,需要手写以下的 import 语句:

import { computed, ref } from 'vue'
const count = ref(0)
const doubled = computed(() => count.value * 2)

使用 unplugin-auto-import 插件后:

const count = ref(0)
const doubled = computed(() => count.value * 2)

使用方法

基本使用

unplugin-auto-import 是基于 unplugin 写的,支持 Vite、Webpack、Rollup、esbuild 多个打包工具。

vite 的使用方式如下:

// vite.config.ts
import AutoImport from 'unplugin-auto-import/vite'

export default defineConfig({
  plugins: [
    AutoImport({
    	imports:[
            // 预设
        ],
    }),
  ],
})

使用预设

unplugin-auto-import 插件一般配合预设进行使用,预设负责告诉插件应该自动引入哪些内容

目前支持:

  • Vue
  • vue-router
  • @vueuse/core
  • react
  • react-router
  • ……,更多请查看这里

预设的配置方式

AutoImport({
  imports [
    // 预设
    'vue',
    'vue-router',
    // 自定义预设
    {
      '@vueuse/core': [
        // 命名导入
        'useMouse', // import { useMouse } from '@vueuse/core',
        // 设置别名
        ['useFetch', 'useMyFetch'], // import { useFetch as useMyFetch } from '@vueuse/core',
      ],
      'axios': [
        // 默认导入
        ['default', 'axios'], // import { default as axios } from 'axios',
      ],
      '[package-name]': [
        '[import-names]',
        // alias
        ['[from]', '[alias]'],
      ],
    },
    // example type import
    {
      from: 'vue-router',
      imports: ['RouteLocationRaw'],
      type: true,
    },
  ],
})

有多种方式设置预设:

  • 字符串语法,最终会被转换成内置的预设(对象语法写的)
  • 对象语法
  • key 为包名
  • value 为数组,对应的是各个自动引入的变量的名称。同时可以设置引入方式(命名导入/默认导入),

对于 Typescript 类型的自动引入,则需要用以下方式:

{
  from: 'vue-router',
  imports: ['RouteLocationRaw'],
  type: true
},

我们来看看 Vue 的预设是怎么写的,完整代码在这里,下面是节选的代码:

export const CommonCompositionAPI: InlinePreset['imports'] = [
  // 声明周期,节选
  'onActivated',
  'onBeforeMount',

  // reactivity,节选
  'computed',
  'ref',
  'watch',

  // 组件 API,节选
  'defineComponent',
  'h',
  'inject',
  'nextTick',

  // Typescript 类型,接续那
  ...[
    'Component',
    'Ref',
    'VNode'
  ].map(name => ({ name, type: true }))
]

export default defineUnimportPreset({
  from: 'vue',
  imports: [
    ...CommonCompositionAPI,
  ]
})

Vue 预设里,本质就是使用对象语法,定义了 Vue 需要被自动导入的内容。

编码问题

要想在项目中优雅地使用自动导入,还要解决以下两个编码的问题:

  • TS 类型丢失,会导致 TS 编译报错
  • Eslint 报错:变量未定义

TS 类型

如果使用 Typescript,需要设置 dts 为 true

AutoImport({
  dts: true // or a custom path
})

插件会在项目根目录生成类型文件 auto-imports.d.ts ,确保该文件在 tsconfig 中被 include

auto-imports.d.ts 有什么作用?

我们来看看它的内容(有节选):

export {}
declare global {
  const h: typeof import('vue')['h']
  const reactive: typeof import('vue')['reactive']
  const ref: typeof import('vue')['ref']
  const watch: typeof import('vue')['watch']
  const watchEffect: typeof import('vue')['watchEffect']
  // 省略其他内容
}

unplugin-auto-import 插件会根据预设内容,生成对应的全局类型声明

有了这些全局类型声明,我们就能够像全局变量那样使用 ref 等 Vue API,不需要先 import 对应的内容,TS 编译也不会报错。

Eslint

如果使用了 eslint,需要设置 eslintrc 字段

AutoImport({
  eslintrc: {
    enabled: true,
  },
})

插件会在项目根目录生成类型文件 .eslintrc-auto-import.json ,确保该文件在 eslint 配置中被 extends

// .eslintrc.js
module.exports = {
  extends: [
    './.eslintrc-auto-import.json',
  ],
}

.eslintrc-auto-import.json 有什么作用?

我们来看看它的内容(有节选):

{
  "globals": {
    "h": true,
    "reactive": true,
    "ref": true,
    "watch": true,
    "watchEffect": true,
  }
}

unplugin-auto-import 插件会根据预设内容,生成对应的 eslint 配置文件,该文件定义了 href 这些为全局变量,不需要引入就能直接使用。这样 ESlint 就不会报变量没有定义的错误了。

实现原理

v0.8.0 来开始,unplugin-auto-import 基于 unimport 开发,所有的转换能力,都是 unimport 提供的,unplugin-auto-import 可以理解成为一个提供了更友好的 API 和功能的包装层。基本上所有新功能都会在 unimport 中开发。

那核心的实现,我们直接去看 unimport 就好了。

eslint 配置的生成是由 unplugin-auto-import 提供

unimport

我们直接看看插件代码

export const defaultIncludes = [/\.[jt]sx?$/, /\.vue$/, /\.vue\?vue/, /\.svelte$/]
export const defaultExcludes = [/[\\/]node_modules[\\/]/, /[\\/]\.git[\\/]/]

export default createUnplugin<Partial<UnimportPluginOptions>>((options = {}) => {

  const ctx = createUnimport(options)

  const filter = createFilter(
    toArray(options.include as string[] || []).length ? options.include : defaultIncludes,
    options.exclude || defaultExcludes
  )
  const dts = options.dts === true
    ? 'unimport.d.ts'
    : options.dts

  return {
    name: 'unimport',
    // 在用户插件执行完之后执行
    enforce: 'post',

    // 过滤文件,默认只处理 、js、jsx、ts、tsx、vue、svelte 文件
    // 默认排除 node_modules 下的文件
    transformInclude (id) {
      return filter(id)
    },

    // 转换文件逻辑
    async transform (code, id) {
      const s = new MagicString(code)

      // 注入 import 语句
      await ctx.injectImports(s, id)

      if (!s.hasChanged()) {
        return
      }
      return {
        code: s.toString(),
        map: s.generateMap()
      }
    },

    // 构建开始时,生成 ts 类型声明文件
    async buildStart () {
      await ctx.init()

      // 生成 Typescript 全局类型声明
      if (options.dts) {
        return fs.writeFile(dts, await ctx.generateTypeDeclarations(), 'utf-8')
      }
    }
  }
})

插件用基于 unplugin 写的,用 unplugin 写的插件,能用在 Vite、Webpack、Rollup、esbuild 多个打包工具,即unplugin 抹平了打包工具间的一些差异

unimport 插件主要的处理逻辑如下:

  1. 过滤出需要处理的文件,对文件进行转换,注入 import 语句
  2. 生成 ts 类型声明文件

unimport 为什么需要在其他插件后执行?

因为有些代码需要先经过处理,才会变成 js,例如 Vue 文件。

测试用例

我们直接使用 unimport 提供的示例,其中一个文件为:

import { Ref } from 'vue'

export const multiplier = ref(2)

export function useDoubled (v: Ref<number>) {
  return computed(() => v.value * multiplier.value)
}

export function bump () {
  multiplier.value += 1
}

const localA = 'localA'
const localB = 'localB'

export {
  localA,
  localB as localBAlias
}

我们通过 vite-plugin-inspect 插件,可以看到该文件被转换的过程:

  1. esbuild 转换
  1. unimport 插件转换

可以看出 unbuild 插件自动加入了 import 语句

  1. import-analysis 插件处理

将 Vue 改为一个可以访问的路径,让 vue 的相关文件在 dev 环境下能够被正常访问到。

如何注入 import 语句

注入 import 语句,是 unimport 的核心逻辑,主要有以下几个步骤:

  1. 初始化预设
  2. 扫描文件
  3. 注入 import

初始化预设

  1. 将字符串的内置预设,标准化为对象语法
  2. 将所有配置对象合并成一个 importMap 对象

importMap 数据结构如下:

{
    reactive: {
        from: 'vue,
        name: 'reactive'
        as: 'reactive'
    },  // 转换成 import { reactive } from 'vue'
    ref: {
        from: 'vue,
        name: 'ref
        as: 'ref
    },  // 转换成 import { ref } from 'vue'

    // ……
}

有了 importMap 对象,就可以快速判断一个标志符,是否需要转换了

扫描和注入

  1. 查找所有可能需要注入的标志符
import { Ref } from 'vue'

export const multiplier = ref(2)

export function useDoubled (v: Ref<number>) {
  return computed(() => v.value * multiplier.value)
}

export function bump () {
  multiplier.value += 1
}

const localA = 'localA'
const localB = 'localB'

export {
  localA,
  localB as localBAlias
}

以上述文件为例,从中找出没有先定义再使用的标志符,排除 js 关键字(function 等)

可以查找到有以下的标志符,未被定义却使用了

  • ref
  • computed

并且这两个标志符都importMap 中能找到,这标明这两个标志符,需要注入 import

因此会注入以下代码:

import { ref, computed } from 'vue';

总结

并非所以依赖都适合自动导入,项目内的代码可能就不一定适合自动引入

因为自动引入后,就能像全局变量那样直接使用,但从开发的角度就会丢失依赖链路,虽然另外生成了 Typescript 声明文件,IDE 能够正常识别, 但对于新加入项目的同学来说,他们不一定知道是自动引入,因此可能会降低了一些可读性。

因此我们要有权衡。

那么,什么样的内容适合自动引入?被广泛认知和使用、不用关注实现、不变的内容

这些内容不关注实现,不会影响可读性,不会影响开发,不会对开发者心智造成影响。

这类内容,就适合自动引入。例如我们例子中的 Vue composition API,就已经成为一种 Vue 开发者共识了。

如果这篇文章对您有所帮助,可以点赞加收藏👍,您的鼓励是我创作路上的最大的动力。也可以关注我的公众号订阅后续的文章:Candy 的修仙秘籍(点击可跳转)

另外,腾讯的实习生校招也开始了,感兴趣的也可以通过公众号找我内推(内推的话先不要到官网填简历)。

正文完