The components property

Nuxt 2.13+ can scan and auto import your components using @nuxt/components module

It is possible to use this feature with Nuxt 2.10 - 2.12. Just manually install and add @nuxt/components to buildModules inside nuxt.config.

• Type: Boolean or Array
• Default: false

When set to true or an options object, Nuxt will include @nuxt/components and auto-import your components wherever you use them within your pages, layouts (and other components).

For more information on how to use, please refer to component auto-discovery documentation for more information.

Configuration

nuxt.config.js

export default {
  // This will automatically load components from `~/components`
  components: true
}

With components: true, by default the ~/components directory will be included.

However you can customize auto-discovery behaviour by providing additional directories to scan:

nuxt.config.js

export default {
  components: [
    // Equivalent to { path: '~/components' }
    '~/components',
    { path: '~/components/other', extensions: ['vue'] }
  ]
}

path

Each item can be either string or object. A string value is a shortcut for { path }.

Don’t worry about ordering or overlapping directories! The components module will take care of it. (Each file will be only matched once with longest path.)

path

• Required
• Type: String

Path (absolute or relative) to the directory containing your components.

You can use Nuxt aliases (~ or @) to refer to directories inside the project or directly use a npm package path (similar to using require within your project).

extensions

• Type: Array<string>
• Default:
  • Extensions supported by Nuxt builder (builder.supportedExtensions)
  • Default supported extensions ['vue', 'js'] or ['vue', 'js', 'ts', 'tsx'] depending on your environment

Example: Support multi-file component structure

If you prefer to split your SFCs into .js, .vue and .css, you could choose only to scan for .vue files:

| components
---| componentC
------| componentC.vue
------| componentC.js
------| componentC.scss

// nuxt.config.js
export default {
  components: [{ path: '~/components', extensions: ['vue'] }]
}

pattern

• Type: string (glob pattern)
• Default: **/*.${extensions.join(',')}

Within the specified path, only files that match this pattern will be included.

ignore

• Type: Array
• Items: string (glob pattern)
• Default: []

Patterns to exclude files within the specified path.

prefix

• Type: String
• Default: '' (no prefix)

Prefix all matched components.

The example below adds the awesome-/Awesome prefix to the name of components in the awesome/ directory.

// nuxt.config.js
export default {
  components: [
    '~/components',
    { path: '~/components/awesome/', prefix: 'awesome' }
  ]
}

| components/
---| awesome/
------| Button.vue
---| Button.vue

<template>
  <div>
    <AwesomeButton>Click on me 🤘</AwesomeButton>
    <button>Click on me</button>
  </div>
</template>

pathPrefix

• Type: Boolean
• Default: true

Prefix component name by its path.

watch

• Type: Boolean
• Default: true

Watch the specified path for changes, including file additions and file deletions.

transpile

• Type: Boolean
• Default: 'auto'

Transpile specified path using build.transpile. By default ('auto') it will set transpile: true if node_modules/ is in path.

level

• Type: Number
• Default: 0

Levels are used to define allow overwriting components that have the same name in two different directories. This can be useful for library authors who want to allow users to override their components, or for custom themes.

export default {
  components: [
    '~/components', // default level is 0
    { path: 'my-theme/components', level: 1 }
  ]
}

A component in ~/components will then overwrite one with the same name in my-theme/components. The lowest value takes priority.

Advanced

Overwriting Components

It is possible to have a way to overwrite components using the level option. This is very useful for modules and theme authors.

Considering this structure:

| node_modules/
---| my-theme/
------| components/
---------| Header.vue
| components/
---| Header.vue

Then defining in the nuxt.config:

components: [
  '~/components', // default level is 0
  { path: 'node_modules/my-theme/components', level: 1 }
]

Our components/Header.vue will overwrite our theme component since the lowest level takes priority.

Library Authors

Making Vue Component libraries with automatic tree-shaking and component registration is now super easy ✨

This module exposes a hook named components:dirs so you can easily extend the directory list without requiring user configuration in your Nuxt module.

Imagine a directory structure like this:

| node_modules/
---| awesome-ui/
------| components/
---------| Alert.vue
---------| Button.vue
------| nuxt.js
| pages/
---| index.vue
| nuxt.config.js

Then in awesome-ui/nuxt.js you can use the components:dir hook:

import { join } from 'path'
export default function () {
  this.nuxt.hook('components:dirs', dirs => {
    // Add ./components dir to the list
    dirs.push({
      path: join(__dirname, 'components'),
      prefix: 'awesome'
    })
  })
}

That’s it! Now in your project, you can import your ui library as a Nuxt module in your nuxt.config.js:

export default {
  buildModules: ['@nuxt/components', 'awesome-ui/nuxt']
}

And directly use the module components (prefixed with awesome-), our pages/index.vue:

<template>
  <div>
    My <AwesomeButton>UI button</AwesomeButton>!
    <awesome-alert>Here's an alert!</awesome-alert>
  </div>
</template>

It will automatically import the components only if used and also support HMR when updating your components in node_modules/awesome-ui/components/.

Next: publish your awesome-ui module to npm and share it with the other Nuxters ✨