Support auto import inside Vue template

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'

Namespace import

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

Will be injected as:

import * as _ 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.

	export async function scanExports (filepath: string, seen = new Set<string>()): Promise<Import[]> {
	if (seen.has(filepath)) {
	// eslint-disable-next-line no-console
	console.warn(`[unimport] "${filepath}" is already scanned, skipping`)
	return []
	}

	seen.add(filepath)
	const imports: Import[] = []
	const code = await readFile(filepath, 'utf-8')

	// Remove those already defined
	for (const regex of excludeRE) {
	for (const match of strippedCode.matchAll(regex)) {
	const segments = [...match[1]?.split(separatorRE) \|\| [], ...match[2]?.split(separatorRE) \|\| []]
	for (const segment of segments) {
	const identifier = segment.replace(importAsRE, '').trim()
	occurrenceMap.delete(identifier)
	}
	}
	}

	const FileExtensionLookup = [
	'.mts',
	'.cts',
	'.ts',
	'.mjs',
	'.cjs',
	'.js'
	]

	if (existsSync(`${subfilepath}${ext}`)) {
	subfilepath = `${subfilepath}${ext}`
	break
	}

unjs / unimport Goto Github PK

unimport's Introduction

unimport

Features

Install

Usage

Plugin Usage

Vite / Rollup

Webpack

Programmatic Usage

Configurations

Imports Item

Named import

Default import

Namespace import

Custom Presets

Built-in Presets

Exports Auto Scan

Type Declarations

Directory Auto Import

Opt-out Auto Import

Acorn Parser

Vue Template Auto Import

Caveats

💻 Development

License

unimport's People

Contributors

Stargazers

Watchers

Forkers

unimport's Issues

Environment

Reproduction

Describe the bug

Additional context

Logs

Environment

Reproduction

Describe the bug

Additional context

Logs

Environment

Reproduction

Describe the bug

Additional context

Logs

Describe the feature

Additional information

Environment

Reproduction

Describe the bug

Additional context

Logs

Environment

Reproduction

Describe the bug

Additional context

Logs

Open

Detected dependencies

Describe the feature

Additional information

Describe the feature

Additional information

Environment

Reproduction

Describe the bug

Additional context

Logs

Describe the feature

Additional information

Describe the feature

Additional information

Describe the feature

1. Magic comments

2. Configuration

3. Auto-injected magic comments

Additional information

Environment