{"id":13810546,"url":"https://github.com/nuxt/components","last_synced_at":"2025-05-13T21:10:41.505Z","repository":{"id":41884282,"uuid":"243228613","full_name":"nuxt/components","owner":"nuxt","description":"Scan and auto import components for Nuxt.js 2.13+","archived":false,"fork":false,"pushed_at":"2025-04-23T18:48:24.000Z","size":1873,"stargazers_count":886,"open_issues_count":63,"forks_count":48,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-04-28T14:05:26.048Z","etag":null,"topics":["components","nuxt","nuxt-components","nuxt-module"],"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/nuxt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["nuxt"]}},"created_at":"2020-02-26T09:55:21.000Z","updated_at":"2025-04-22T10:55:51.000Z","dependencies_parsed_at":"2022-08-11T20:10:17.329Z","dependency_job_id":"1f382ac7-59d4-4cda-b62b-b9d74fbcaf19","html_url":"https://github.com/nuxt/components","commit_stats":{"total_commits":291,"total_committers":31,"mean_commits":9.387096774193548,"dds":0.6907216494845361,"last_synced_commit":"86ab5e0b508186f647c3d79ac4a4cc67cae11f19"},"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuxt%2Fcomponents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuxt%2Fcomponents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuxt%2Fcomponents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuxt%2Fcomponents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nuxt","download_url":"https://codeload.github.com/nuxt/components/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251326836,"owners_count":21571634,"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":["components","nuxt","nuxt-components","nuxt-module"],"created_at":"2024-08-04T02:00:59.229Z","updated_at":"2025-04-28T14:05:30.628Z","avatar_url":"https://github.com/nuxt.png","language":"TypeScript","funding_links":["https://github.com/sponsors/nuxt"],"categories":["TypeScript"],"sub_categories":[],"readme":"![@nuxt/components](https://user-images.githubusercontent.com/904724/99790294-2f75d300-2b24-11eb-8114-0a2569913fae.png)\n\n# @nuxt/components\n\n[![npm version][npm-version-src]][npm-version-href]\n[![npm downloads][npm-downloads-src]][npm-downloads-href]\n[![Github Actions CI][github-actions-ci-src]][github-actions-ci-href]\n[![Codecov][codecov-src]][codecov-href]\n[![License][license-src]][license-href]\n\n\u003e Module to scan and auto import components for Nuxt 2.13+\n\n- [🎲\u0026nbsp; Play on CodeSandbox](https://githubbox.com/nuxt/components/tree/main/example)\n- [🎬\u0026nbsp; Demonstration video (49s)](https://www.youtube.com/watch?v=lQ8OBrgVVr8)\n- [📖\u0026nbsp; Release Notes](./CHANGELOG.md)\n\n## Table of Contents\n\n- [Features](#features)\n- [Usage](#usage)\n- [Lazy Imports](#lazy-imports)\n- [Overwriting Components](#overwriting-components)\n- [Directories](#directories)\n- [Directory Properties](#directory-properties)\n- [Library authors](#library-authors)\n- [License](#license)\n\n## Features\n\n- Automatically scan `components/` directory\n- No need to manually import components anymore\n- Multiple paths with customizable prefixes and lookup/ignore patterns\n- Lazy loading (Async components)\n- Production code-splitting optimization (loader)\n- Hot reloading\n- Module integration ([library authors](#library-authors))\n- Fully tested\n\n## Usage\n\nSet the `components` option in `nuxt.config`:\n\n```js\nexport default {\n  components: true\n}\n```\n\n**Note:** If using nuxt `2.10...2.13`, you have to also manually install and add `@nuxt/components` to `buildModules` inside `nuxt.config`.\n\n**Create your components:**\n\n```bash\n| components/\n---| ComponentFoo.vue\n---| ComponentBar.vue\n```\n\n**Use them whenever you want, they will be auto imported in `.vue` files :**\n\n```html\n\u003ctemplate\u003e\n  \u003cComponentFoo /\u003e\n  \u003ccomponent-bar /\u003e\n\u003c/template\u003e\n```\n\nNo need anymore to manually import them in the `script` section!\n\nSee [live demo](https://codesandbox.io/s/nuxt-components-cou9k) or [video example](https://www.youtube.com/watch?v=lQ8OBrgVVr8).\n\n### Lazy Imports\n\nNuxt by default does code-splitting per page and components. But sometimes we also need to lazy load them:\n\n- Component size is rather big (or has big dependencies imported) like a text-editor\n- Component is rendered conditionally with `v-if` or being in a modal\n\nIn order to [lazy load](https://webpack.js.org/guides/lazy-loading/) a component, all we need to do is to add `Lazy` prefix to component name.\n\nYou now can easily import a component on-demand:\n\n```html\n\u003ctemplate\u003e\n  \u003cLazyComponentFoo v-if=\"foo\" /\u003e\n  \u003cbutton @click=\"loadFoo\"\u003e\n    Load Foo\n  \u003c/button\u003e\n\u003c/template\u003e\n\n\u003cscript\u003e\n  export default {\n    data() {\n      return {\n        foo: null\n      }\n    },\n    methods: {\n      async loadFoo() {\n        this.foo = await this.$axios.$get('foo')\n      }\n    }\n  }\n\u003c/script\u003e\n```\n\nIf you want to prefetch or preload the components with `Lazy` prefix, you can configure it by [prefetch/preload options](#prefetch/preload).\n\n### Nested Components\n\nIf you have components in nested directories:\n\n```bash\n| components/\n---| my/\n------| form/\n---------| TextArea.vue\n```\n\nThe component name will contain its path:\n\n```html\n\u003cMyFormTextArea /\u003e\n```\n\nFor clarity, it is recommended that component file name matches its name. You can also use `MyFormTextArea.vue` as name with same directory structure.\n\nIf for any reason different prefix is desired, we can add specific directory with the `prefix` option: (See [directories](#directories) section)\n\n```js\ncomponents: ['~/components/', { path: '~/components/foo/', prefix: 'foo' }]\n```\n\n## Overwriting Components\n\nIt is possible to have a way to overwrite components using the [level](#level) option. This is very useful for modules and theme authors.\n\nConsidering this structure:\n\n```bash\n| node_modules/\n---| my-theme/\n------| components/\n---------| Header.vue\n| components/\n---| Header.vue\n```\n\nThen defining in the `nuxt.config`:\n\n```js\ncomponents: [\n  '~/components', // default level is 0\n  { path: 'node_modules/my-theme/components', level: 1 }\n]\n```\n\nOur `components/Header.vue` will overwrite our theme component since the lowest level overwrites.\n\n## Directories\n\nBy setting `components: true`, default `~/components` directory will be included.\nHowever you can customize module behaviour by providing directories to scan:\n\n```js\nexport default {\n  components: [\n    '~/components', // shortcut to { path: '~/components' }\n    { path: '~/components/awesome/', prefix: 'awesome' }\n  ]\n}\n```\n\nEach item can be either string or object. String is shortcut to `{ path }`.\n\n**Note:** Don't worry about ordering or overlapping directories! Components module will take care of it. Each file will be only matched once with longest path.\n\n### Directory Properties\n\n#### path\n\n- Required\n- Type: `String`\n\nPath (absolute or relative) to the directory containing your components.\n\nYou can use Nuxt aliases (`~` or `@`) to refer to directories inside project or directly use a npm package path similar to require.\n\n#### extensions\n\n- Type: `Array\u003cstring\u003e`\n- Default:\n  - Extensions supported by Nuxt builder (`builder.supportedExtensions`)\n  - Default supported extensions `['vue', 'js']` or `['vue', 'js', 'ts', 'tsx']` depending on your environment\n\n**Example:** Support multi-file component structure\n\nIf you prefer to split your SFCs into `.js`, `.vue` and `.css`, you can only enable `.vue` files to be scanned:\n\n```\n| components\n---| componentC\n------| componentC.vue\n------| componentC.js\n------| componentC.scss\n```\n\n```js\n// nuxt.config.js\nexport default {\n  components: [{ path: '~/components', extensions: ['vue'] }]\n}\n```\n\n#### pattern\n\n- Type: `string` ([glob pattern](https://github.com/isaacs/node-glob#glob-primer))\n- Default: `**/*.${extensions.join(',')}`\n\nAccept Pattern that will be run against specified `path`.\n\n#### ignore\n\n- Type: `Array`\n- Items: `string` ([glob pattern](https://github.com/isaacs/node-glob#glob-primer))\n- Default: `[]`\n\nIgnore patterns that will be run against specified `path`.\n\n#### prefix\n\n- Type: `String`\n- Default: `''` (no prefix)\n\nPrefix all matched components.\n\nExample below adds `awesome-`/`Awesome` prefix to the name of components in `awesome/` directory.\n\n```js\n// nuxt.config.js\nexport default {\n  components: [\n    '~/components',\n    { path: '~/components/awesome/', prefix: 'awesome' }\n  ]\n}\n```\n\n```bash\ncomponents/\n  awesome/\n    Button.vue\n  Button.vue\n```\n\n```html\n\u003ctemplate\u003e\n  \u003cdiv\u003e\n    \u003cAwesomeButton\u003eClick on me 🤘\u003c/AwesomeButton\u003e\n    \u003cbutton\u003eClick on me\u003c/button\u003e\n  \u003c/div\u003e\n\u003c/template\u003e\n```\n\n#### pathPrefix\n\n- Type: `Boolean`\n- Default: `true`\n\nPrefix component name by it's path\n\n#### watch\n\n- Type: `Boolean`\n- Default: `true`\n\nWatch specified `path` for changes, including file additions and file deletions.\n\n#### transpile\n\n- Type: `Boolean`\n- Default: `'auto'`\n\nTranspile specified `path` using [`build.transpile`](https://nuxtjs.org/api/configuration-build#transpile), by default (`'auto'`) it will set `transpile: true` if `node_modules/` is in `path`.\n\n#### level\n\n- Type: `Number`\n- Default: `0`\n\nLevel are use to define a hint when overwriting the components which have the same name in two different directories, this is useful for theming.\n\n```js\nexport default {\n  components: [\n    '~/components', // default level is 0\n    { path: 'my-theme/components', level: 1 }\n  ]\n}\n```\n\nComponents having the same name in `~/components` will overwrite the one in `my-theme/components`, learn more in [Overwriting Components](#overwriting-components). The lowest value will overwrite.\n\n#### prefetch/preload\n\n- Type: `Boolean/Number`\n- Default: `false`\n\nThese properties are used in production to configure how [components with `Lazy` prefix](#Lazy-Imports) are handled by Wepack via its magic comments, learn more in [Wepack's official documentation](https://webpack.js.org/api/module-methods/#magic-comments).\n\n```js\nexport default {\n  components: [{ path: 'my-theme/components', prefetch: true }]\n}\n```\n\nyields:\n\n```js\n// plugin.js\nconst componets = {\n  MyComponentA: import(/* webpackPrefetch: true */ ...),\n  MyComponentB: import(/* webpackPrefetch: true */ ...)\n}\n```\n\n#### isAsync\n\n- Type: Boolean\n- Default: `false` unless component name ends with `.async.vue`\n\nThis flag indicates, component should be loaded async (with a seperate chunk) regardless of using `Lazy` prefix or not.\n\n## Migration guide\n\n## `v1` to `v2`\n\nStarting with `nuxt@2.15`, Nuxt uses `@nuxt/components` v2:\n\n- All components are globally available so you can move `components/global/`\n  to `components/` and `global: true` is not required anymore\n- Full path inside `components` is used to prefix component names. If you were structing your\n  components in multiple directories, should either add prefix or register in `components` section of `nuxt.config` or use new `pathPrefix` option.\n\n**Example:**\n\n```\ncomponents\n├── atoms\n│   └── icons\n├── molecules\n│   └── illustrations\n├── organisms\n│   └── ads\n└── templates\n    ├── blog\n    └── home\n```\n\n```js\n// nuxt.config.js\nexport default {\n  components: [\n    '~/components/templates',\n    '~/components/atoms',\n    '~/components/molecules',\n    '~/components/organisms'\n  ]\n}\n```\n\n## Library Authors\n\nMaking Vue Component libraries with automatic tree-shaking and component registration is now damn easy ✨\n\nThis module expose a hook named `components:dirs` so you can easily extend the directory list without updating user configuration in your Nuxt module.\n\nImagine a directory structure like this:\n\n```bash\n| node_modules/\n---| awesome-ui/\n------| components/\n---------| Alert.vue\n---------| Button.vue\n------| nuxt.js\n| pages/\n---| index.vue\n| nuxt.config.js\n```\n\nThen in `awesome-ui/nuxt.js` you can use the `components:dirs` hook:\n\n```js\nimport { join } from 'path'\n\nexport default function() {\n  this.nuxt.hook('components:dirs', dirs =\u003e {\n    // Add ./components dir to the list\n    dirs.push({\n      path: join(__dirname, 'components'),\n      prefix: 'awesome'\n    })\n  })\n}\n```\n\nThat's it! Now in your project, you can import your ui library as a Nuxt module in your `nuxt.config.js`:\n\n```js\nexport default {\n  buildModules: ['@nuxt/components', 'awesome-ui/nuxt']\n}\n```\n\nAnd directly use the module components (prefixed with `awesome-`), our `pages/index.vue`:\n\n```vue\n\u003ctemplate\u003e\n  \u003cdiv\u003e\n    My \u003cAwesomeButton\u003eUI button\u003c/AwesomeButton\u003e!\n    \u003cawesome-alert\u003eHere's an alert!\u003c/awesome-alert\u003e\n  \u003c/div\u003e\n\u003c/template\u003e\n```\n\nIt will automatically import the components only if used and also support HMR when updating your components in `node_modules/awesome-ui/components/`.\n\nNext: publish your `awesome-ui` module to [npm](https://www.npmjs.com) and share it with the other Nuxters ✨\n\n## License\n\n[MIT](./LICENSE)\n\n\u003c!-- Badges --\u003e\n\n[npm-version-src]: https://img.shields.io/npm/v/@nuxt/components/latest.svg?style=flat-square\n[npm-version-href]: https://npmjs.com/package/@nuxt/components\n[npm-downloads-src]: https://img.shields.io/npm/dt/@nuxt/components.svg?style=flat-square\n[npm-downloads-href]: https://npmjs.com/package/@nuxt/components\n[github-actions-ci-src]: https://img.shields.io/github/workflow/status/nuxt/typescript/test?label=ci\u0026style=flat-square\n[github-actions-ci-href]: https://github.com/nuxt/components/actions?query=workflow%3Aci\n[codecov-src]: https://img.shields.io/codecov/c/github/nuxt/components.svg?style=flat-square\n[codecov-href]: https://codecov.io/gh/nuxt/components\n[license-src]: https://img.shields.io/npm/l/@nuxt/components.svg?style=flat-square\n[license-href]: https://npmjs.com/package/@nuxt/components\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnuxt%2Fcomponents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnuxt%2Fcomponents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnuxt%2Fcomponents/lists"}