{"id":13880745,"url":"https://github.com/unjs/unimport","last_synced_at":"2025-05-13T23:08:18.812Z","repository":{"id":37077458,"uuid":"459141315","full_name":"unjs/unimport","owner":"unjs","description":"Unified utils for auto importing APIs in modules.","archived":false,"fork":false,"pushed_at":"2025-05-04T06:41:39.000Z","size":3081,"stargazers_count":601,"open_issues_count":28,"forks_count":72,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-04T07:28:03.749Z","etag":null,"topics":["esm","esmodule","vite","webpack"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-14T11:51:29.000Z","updated_at":"2025-05-04T06:41:42.000Z","dependencies_parsed_at":"2023-02-19T16:45:45.056Z","dependency_job_id":"8a1c0729-0f1f-4b9e-9790-26461570637d","html_url":"https://github.com/unjs/unimport","commit_stats":{"total_commits":585,"total_committers":53,"mean_commits":"11.037735849056604","dds":0.4478632478632478,"last_synced_commit":"740dc871e67ebe4a811419c31064c7012c724b6f"},"previous_names":[],"tags_count":120,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unjs%2Funimport","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unjs%2Funimport/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unjs%2Funimport/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unjs%2Funimport/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unjs","download_url":"https://codeload.github.com/unjs/unimport/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254041567,"owners_count":22004744,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esm","esmodule","vite","webpack"],"created_at":"2024-08-06T08:03:26.718Z","updated_at":"2025-05-13T23:08:13.799Z","avatar_url":"https://github.com/unjs.png","language":"TypeScript","readme":"# unimport\n\n[![npm version][npm-version-src]][npm-version-href]\n[![npm downloads][npm-downloads-src]][npm-downloads-href]\n[![Codecov][codecov-src]][codecov-href]\n\n\u003e Unified utils for auto importing APIs in modules, used in [nuxt](https://github.com/nuxt/nuxt) and [unplugin-auto-import](https://github.com/antfu/unplugin-auto-import)\n\n## Features\n\n- Auto import register APIs for Vite, Webpack or esbuild powered by [unplugin](https://github.com/unjs/unplugin)\n- TypeScript declaration file generation\n- Auto import for custom APIs defined under specific directories\n- Auto import for Vue template\n\n## Install\n\n```sh\n# npm\nnpm install unimport\n\n# yarn\nyarn add unimport\n\n# pnpm\npnpm install unimport\n```\n\n## Usage\n\n### Plugin Usage\n\nPowered by [unplugin](https://github.com/unjs/unplugin), `unimport` provides a plugin interface for bundlers.\n\n#### Vite / Rollup\n\n```ts\n// vite.config.js / rollup.config.js\nimport Unimport from 'unimport/unplugin'\n\nexport default {\n  plugins: [\n    Unimport.vite({ /* plugin options */ })\n  ]\n}\n```\n\n#### Webpack\n\n```ts\n// webpack.config.js\nimport Unimport from 'unimport/unplugin'\n\nmodule.exports = {\n  plugins: [\n    Unimport.webpack({ /* plugin options */ })\n  ]\n}\n```\n\n### Programmatic Usage\n\n\u003c!-- eslint-skip --\u003e\n\n```js\n// ESM\nimport { createUnimport } from 'unimport'\n\n// CommonJS\nconst { createUnimport } = require('unimport')\n```\n\n```js\nconst { injectImports } = createUnimport({\n  imports: [{ name: 'fooBar', from: 'test-id' }]\n})\n\n// { code: \"import { fooBar } from 'test-id';console.log(fooBar())\" }\nconsole.log(injectImports('console.log(fooBar())'))\n```\n\n## Configurations\n\n### Imports Item\n\n###### Named import\n\n```ts\nimports: [\n  { name: 'ref', from: 'vue' },\n  { name: 'useState', as: 'useSignal', from: 'react' },\n]\n```\n\nWill be injected as:\n\n```ts\nimport { useState as useSignal } from 'react'\nimport { ref } from 'vue'\n```\n\n###### Default import\n\n```ts\nimports: [\n  { name: 'default', as: '_', from: 'lodash' }\n]\n```\n\nWill be injected as:\n\n```ts\nimport _ from 'lodash'\n```\n\n###### Namespace import\n\n```ts\nimports: [\n  { name: '*', as: '_', from: 'lodash' }\n]\n```\n\nWill be injected as:\n\n```ts\nimport * as _ from 'lodash'\n```\n\n###### Export assignment import\n\nThis is a special case for libraries authored with [TypeScript's `export =` syntax](https://www.typescriptlang.org/docs/handbook/modules/reference.html#export--and-import--require). You don't need it the most of the time.\n\n```ts\nimports: [\n  { name: '=', as: 'browser', from: 'webextension-polyfill' }\n]\n```\n\nWill be injected as:\n\n```ts\nimport browser from 'webextension-polyfill'\n```\n\nAnd the type declaration will be added as:\n\n```ts\nconst browser: typeof import('webextension-polyfill')\n```\n\n###### Custom Presets\n\nPresets are provided as a shorthand for declaring imports from the same package:\n\n```ts\npresets: [\n  {\n    from: 'vue',\n    imports: [\n      'ref',\n      'reactive',\n      // ...\n    ]\n  }\n]\n```\n\nWill be equivalent as:\n\n```ts\nimports: [\n  { name: 'ref', from: 'vue' },\n  { name: 'reactive', from: 'vue' },\n  // ...\n]\n```\n\n###### Built-in Presets\n\n`unimport` also provides some builtin presets for common libraries:\n\n```ts\npresets: [\n  'vue',\n  'pinia',\n  'vue-i18n',\n  // ...\n]\n```\n\nYou can check out [`src/presets`](./src/presets/) for all the options available or refer to the type declaration.\n\n###### Exports Auto Scan\n\nSince `unimport` v0.7.0, we also support auto scanning the examples from a local installed package, for example:\n\n```ts\npresets: [\n  {\n    package: 'h3',\n    ignore: ['isStream', /^[A-Z]/, /^[a-z]*$/, r =\u003e r.length \u003e 8]\n  }\n]\n```\n\nThis will be expanded into:\n\n```ts\nimports: [\n  {\n    from: 'h3',\n    name: 'appendHeader',\n  },\n  {\n    from: 'h3',\n    name: 'appendHeaders',\n  },\n  {\n    from: 'h3',\n    name: 'appendResponseHeader',\n  },\n  // ...\n]\n```\n\nThe `ignore` option is used to filter out the exports, it can be a string, regex or a function that returns a boolean.\n\nBy default, the result is strongly cached by the version of the package. You can disable this by setting `cache: false`.\n\n### Type Declarations\n\n```ts\nUnimport.vite({\n  dts: true // or a path to generated file\n})\n```\n\n### Directory Auto Import\n\n```ts\nUnimport.vite({\n  dirs: [\n    './composables/*',\n  ]\n})\n```\n\nScan for modules under `./composables` and auto-import the named exports.\n\n#### Nested Directories\n\n```ts\nUnimport.vite({\n  dirs: [\n    './composables/**/*',\n    {\n      glob: './composables/nested/**/*',\n      types: false // disable scan the type declarations\n    }\n  ]\n})\n```\n\nNamed exports for modules under `./composables/**/*` will be registered for auto imports, and filter out the types in `./composables/nested/**/*`.\n\n#### Directory Scan Options\n\nYou can also provide custom options for directory scan, for example:\n\n```ts\nUnimport.vite({\n  dirsScanOptions: {\n    filePatterns: ['*.ts'], // optional, default `['*.{ts,js,mjs,cjs,mts,cts}']`, glob patterns for matching files\n    fileFilter: file =\u003e file.endsWith('.ts'), // optional, default `() =\u003e true`, filter files\n    types: true, // optional, default `true`, enable/disable scan the type declarations\n    cwd: process.cwd(), // optional, default `process.cwd()`, custom cwd for directory scan\n  },\n  dirs: [\n    './composables/**/*',\n    {\n      glob: './composables/nested/**/*',\n      types: false\n    }\n  ]\n})\n```\n\n### Opt-out Auto Import\n\nYou can opt-out auto-import for specific modules by adding a comment:\n\n```ts\n// @unimport-disable\n```\n\nIt can be customized by setting `commentsDisable`:\n\n```ts\nUnimport.vite({\n  commentsDisable: [\n    '@unimport-disable',\n    '@custom-imports-disable',\n  ]\n})\n```\n\n### Acorn Parser\n\nBy default, `unimport` uses RegExp to detect unimport entries. In some cases, RegExp might not be able to detect all the entries (false positive \u0026 false negative).\n\nWe introduced a new AST-based parser powered by [acorn](https://github.com/acornjs/acorn), providing a more accurate result. The limitation is when using Acorn, it assumes all input code are valid and vanilla JavaScript code.\n\n```ts\nUnimport.vite({\n  parser: 'acorn'\n})\n```\n\n### Vue Template Auto Import\n\nIn 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`:\n\n```ts\nUnimport.vite({\n  addons: {\n    vueTemplate: true\n  }\n})\n```\n\n#### Caveats\n\nWhen auto-import a ref, inline operations won't be auto-unwrapped.\n\n```ts\nexport const counter = ref(0)\n```\n\n```html\n\u003ctemplate\u003e\n  \u003c!-- this is ok --\u003e\n  \u003cdiv\u003e{{ counter }}\u003c/div\u003e\n\n  \u003c!-- counter here is a ref, this won't work, volar will throw --\u003e\n  \u003cdiv\u003e{{ counter + 1 }}\u003c/div\u003e\n\n  \u003c!-- use this instead --\u003e\n  \u003cdiv\u003e{{ counter.value + 1 }}\u003c/div\u003e\n\u003c/template\u003e\n```\n\nWe recommend using [Volar](https://github.com/johnsoncodehk/volar) for type checking, which will help you to identify the misusage.\n\n### Vue Directives Auto Import and TypeScript Declaration Generation\n\nIn Vue's template, the usage of directives is in a different context than plain modules. Thus some custom transformations are required. To enable it, set `addons.vueDirectives` to `true`:\n\n```ts\nUnimport.vite({\n  addons: {\n    vueDirectives: true\n  }\n})\n```\n\n#### Library Authors\n\nWhen including directives in your presets, you should:\n- provide the corresponding imports with `meta.vueDirective` set to `true`, otherwise, `unimport` will not be able to detect your directives.\n- use named exports for your directives, or use default export and use `as` in the Import.\n- set `dtsDisabled` to `true` if you provide a type declaration for your directives.\n\n```ts\nimport type { InlinePreset } from 'unimport'\nimport { defineUnimportPreset } from 'unimport'\n\nexport const composables = defineUnimportPreset({\n  from: 'my-unimport-library/composables',\n  /* imports and other options */\n})\n\nexport const directives = defineUnimportPreset({\n  from: 'my-unimport-library/directives',\n  // disable dts generation globally\n  dtsEnabled: false,\n  // you can declare the vue directive globally\n  meta: {\n    vueDirective: true\n  },\n  imports: [{\n    name: 'ClickOutside',\n    // disable dts generation per import\n    dtsEnabled: false,\n    // you can declare the vue directive per import\n    meta: {\n      vueDirective: true\n    }\n  }, {\n    name: 'default',\n    // you should declare `as` for default exports\n    as: 'Focus'\n  }]\n})\n```\n\n#### Using Directory Scan and Local Directives\n\nIf you add a directory scan for your local directives in the project, you need to:\n- provide `isDirective` in the `vueDirectives`: `unimport` will use it to detect them (will never be called for imports with `meta.vueDirective` set to `true`).\n- use always named exports for your directives.\n\n```ts\nUnimport.vite({\n  dirs: ['./directives/**'],\n  addons: {\n    vueDirectives: {\n      isDirective: (normalizedImportFrom, _importEntry) =\u003e {\n        return normalizedImportFrom.includes('/directives/')\n      }\n    }\n  }\n})\n```\n\n## 💻 Development\n\n- Clone this repository\n- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable` (use `npm i -g corepack` for Node.js \u003c 16.10)\n- Install dependencies using `pnpm install`\n- Run interactive tests using `pnpm dev`\n\n## License\n\nMade with 💛\n\nPublished under [MIT License](./LICENSE).\n\n\u003c!-- Badges --\u003e\n[npm-version-src]: https://img.shields.io/npm/v/unimport?style=flat-square\n[npm-version-href]: https://npmjs.com/package/unimport\n\n[npm-downloads-src]: https://img.shields.io/npm/dm/unimport?style=flat-square\n[npm-downloads-href]: https://npmjs.com/package/unimport\n\n[github-actions-src]: https://img.shields.io/github/workflow/status/unjs/unimport/ci/main?style=flat-square\n[github-actions-href]: https://github.com/unjs/unimport/actions?query=workflow%3Aci\n\n[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/unimport/main?style=flat-square\n[codecov-href]: https://codecov.io/gh/unjs/unimport\n","funding_links":[],"categories":["TypeScript","webpack"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funjs%2Funimport","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funjs%2Funimport","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funjs%2Funimport/lists"}