@nuxt/components

Module to scan and auto import components for Nuxt.js 2.10+

• 🎲 Play on CodeSandbox
• 🎬 Demonstration video (49s)
• 📖 Release Notes

Table of Contents

• Features
• Usage
• Setup
• Options
• Library authors
• License

Features

• Scan and auto import components
• Multiple paths with customizable prefixes and lookup/ignore patterns
• Dynamic import (aka Lazy loading) Support
• Hot reloading Support
• Transpiling Support (useful for component libraries' authors)
• Fully tested!

Usage

Create your components :

components/
  ComponentFoo.vue
  ComponentBar.vue

Use them whenever you want, they will be auto imported in .vue files :

<template>
  <ComponentFoo />
  <component-bar />
</template>

No need anymore to manually import them in the script section !

See live demo.

Dynamic imports

To make a component imported dynamically (lazy loaded), all you need is adding a Lazy prefix in your templates.

If you think this prefix should be customizable, feel free to create a feature issue !

You are now being able to easily import a component on-demand :

<template>
  <LazyComponentFoo v-if="foo" />
  <button @click="loadFoo">
    Load Foo
  </button>
</template>

<script>
export default {
  data () {
    return {
      foo: null
    }
  },
  methods: {
    async loadFoo () {
      this.foo = await this.$axios.$get('foo')
    }
  }
}
</script>

Nested components

If you have components in nested directories:

components/
  foo/
    Bar.vue

The component name will be based on its filename:

<Bar />

We do recommend to use the directory name in the filename for clarity in order to use <FooBar />:

components/
  foo/
    FooBar.vue

If you want to keep the filename as Bar.vue, consider using the prefix option:

components: {
  dirs: [
    '~/components/',
    {
      path: '~/components/foo/',
      prefix: 'foo'
    }
  ]
]

Setup

Nuxt 2.13+

If you are using nuxt-edge or Nuxt 2.13+ (release soon 👀) simply set components: true in your nuxt.config.js:

export default {
  components: true
}

Nuxt 2.10+

1. Add @nuxt/components dependency to your project

yarn add --dev @nuxt/components # or npm install --save-dev @nuxt/components

2. Add @nuxt/components to the buildModules section of nuxt.config.js

export default {
  buildModules: [
    // TODO: Remove when upgrading to nuxt 2.13+
    '@nuxt/components'
  ]
}

Nuxt < 2.10

Please upgrade your Nuxt version in order to use this module.

Options

You can define the options of the module in the components property of your nuxt.config.js:

export default {
  buildModules: [
    '@nuxt/components',
  ],
  components: {
    /* module options */
  }
}

dirs

• Type: Array
  • Items: String or Object (see definition below)
• Default: ['~/components']

List of directories to scan, with customizable options when using Object syntax.

String items are shortcut to Object with only path provided :

'~/components' === { path: '~/components' }

Object syntax properties

path

• Required
• Type: String

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

We highly recommend using Nuxt aliases :

Alias	Directory
~ or @	srcDir
~~ or @@	rootDir

pattern

• Type: String (must follow glob pattern style : https://github.com/isaacs/node-glob#glob-primer)
• Default: **/*.${extensions.join(',')}
  • extensions being Nuxt builder.supportedExtensions
  • Resulting in **/*.{vue,js} or **/*.{vue,js,ts,tsx} depending on your environment

Accept Pattern that will be run against specified path.

ignore

• Type: Array
• Items: String (must follow glob pattern style : https://github.com/isaacs/node-glob#glob-primer)
• Default: []

Ignore patterns that will be run against specified path.

prefix

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

Prefix components for specified path.

// nuxt.config.js
export default {
  components: {
    dirs: [
      '~/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>

watch

• Type: Boolean
• Default: true

Watch 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.

Library authors

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

This module expose a hook named components:dirs so you can easily extend the directory list without updating 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 ✨

License

MIT License

Copyright (c) Nuxt.js Team