unimport

When using unimport as a plugin (e.g., via unplugin), you can provide an options object of type UnimportPluginOptions. This allows you to control which files are processed, how TypeScript definitions are generated, and whether auto-imports are enabled.

Options

• include: A FilterPattern defining which files to include. Defaults to [/\.[jt]sx?$/, /\.vue$/, /\.vue\?vue/, /\.svelte$/] if not provided.
• exclude: A FilterPattern defining which files to exclude. Defaults to [/[\\/]node_modules[\\/]/, /[\\/]\.git[\\/]/] if not provided.
• dts: Controls TypeScript declaration generation.
  • true: Generates unimport.d.ts.
  • string: Generates a file at the specified path.
  • false (or omitted): Disables generation.
• autoImport: (Boolean, default: true) Enables implicit auto-importing of symbols.

// Example configuration shape
{
  include: /src/,
  exclude: /tests/,
  dts: 'my-imports.d.ts',
  autoImport: true
}

When initializing unimport, you can provide an UnimportOptions object to define how auto-imports behave. Key configuration areas include:

• Imports & Presets: Define specific imports or use presets (which can be InlinePreset or PackagePreset).
• Addons: Enable specialized features like vueTemplate or vueDirectives.
• Scanning: Specify directories to scan using dirs and dirsScanOptions.
• Parsing: Choose a parser ('regex', 'acorn', or 'oxc').
• Injection: Control where imports are placed using injectAtEnd and whether to mergeExisting imports.
• Virtual Modules: Define virtualImports to expose all registered auto-imports via a virtual module.

const options: UnimportOptions = {
  imports: [{ name: 'ref', from: 'vue' }],
  presets: ['vue'],
  addons: {
    vueTemplate: true,
    vueDirectives: true
  },
  virtualImports: ['virtual:imports'],
  dirs: ['src/composables'],
  parser: 'oxc'
};

To use unimport programmatically, call createUnimport(opts) with your desired configuration. This returns an Unimport instance that provides methods for scanning, detecting, and injecting imports into your code.

Common configuration options include:

• imports: An array of static imports to include.
• presets: An array of built-in presets to resolve.
• dirs: Directories to scan for exports.
• collectMeta: If true, enables metadata collection for tracking injection usage.
• commentsDisable: Array of comment strings that, if present in a file, prevent any imports from being injected (default: ['@unimport-disable', '@imports-disable']).
• commentsDebug: Array of comment strings that, if present, trigger debug logging of detected imports (default: ['@unimport-debug', '@imports-debug']).

import { createUnimport } from 'unimport'

const unimport = createUnimport({
  imports: ['myStaticImport'],
  presets: ['vue'],
  dirs: ['./src/components']
})

The stringifyImports function converts an array of Import objects into valid JavaScript import or require statements. It supports both ESM (import ... from ...) and CommonJS (const ... = require(...)) formats.

It handles several special import patterns:

• Side-effect imports: import 'module' or require('module').
• Default imports: import name from 'module' or const { default: name } = require('module').
• Namespace imports: import * as name from 'module' or const name = require('module').
• Named imports: import { a, b } from 'module' or const { a, b } = require('module').
• Import Attributes: Supports the with { ... } syntax for ESM imports.

import { stringifyImports } from 'unimport'

// Example usage (conceptual):
// const code = stringifyImports(myImports, false) // ESM
// const cjsCode = stringifyImports(myImports, true) // CJS

The addImportToCode function uses magic-string to programmatically inject import statements into existing source code. It is highly configurable to allow for precise placement and merging.

Key Options:

• code: The original source code (string or MagicString).
• imports: An array of Import objects to inject.
• isCJS: Whether to generate CommonJS require statements.
• mergeExisting: If true and using ESM, it attempts to merge new imports into existing curly-brace imports from the same module.
• injectAtLast: If true, injects imports at the end of the import block rather than at the top.
• firstOccurrence: The index used to determine where to inject if not at the very top.
• onResolved: A callback to transform the imports before they are stringified.
• onStringified: A callback to transform the resulting import string.

import { addImportToCode } from 'unimport'

const result = addImportToCode(originalCode, imports, false, true)
console.log(result.code)

The injectImports method is the primary way to automatically add import statements to a string of code (or a MagicString instance). It detects which imports are needed based on the code content and returns a result containing the modified code and the list of imports added.

Key features:

• Automatic Detection: Uses detectImports to find matches.
• Context Awareness: Handles CJS/ESM contexts.
• Customization: Supports mergeExisting and injectAtEnd options.
• Addon Support: Allows addons to transform the code or modify the resolved imports before injection.

Options (InjectImportsOptions):

• mergeExisting: Whether to merge with existing imports in the file.
• injectAtEnd: Whether to inject imports at the end of the file instead of the top.

Returns: An object containing the modified MagicString (or string) and the imports array.

const result = await unimport.injectImports(code, 'my-file.ts', {
  mergeExisting: true,
  injectAtEnd: false
})

console.log(result.imports)
// The modified code can be accessed via result.s.toString()