diff --git a/docs/content/3.docs/2.directory-structure/4.components.md b/docs/content/3.docs/2.directory-structure/4.components.md index ad20730bc5..0699e7918a 100644 --- a/docs/content/3.docs/2.directory-structure/4.components.md +++ b/docs/content/3.docs/2.directory-structure/4.components.md @@ -7,3 +7,138 @@ head.title: Components directory # Components directory The `components/` directory is where you put all your Vue components which can then be imported inside your pages or other components ([learn more](https://v3.vuejs.org/guide/component-basics.html)). + +Nuxt automatically imports any components in your `components/` directory (along with components that are registered by any modules you may be using). + +```bash +| components/ +--| TheHeader.vue +--| TheFooter.vue +``` + +```html{}[layouts/default.vue] + +``` + +## Component Names + +If you have components in nested directories such as: + +```bash +| components/ +--| base/ +----| foo/ +------| Button.vue +``` + +The component name will be based on its own path directory and filename, with duplicate segments being removed. Therefore, the component will be: + +```html + +``` + +::alert +For clarity, it is recommend that the component file name matches its name. (So, in the example above, you could rename `Button.vue` to be `BaseFooButton.vue`.) +:: + +## Dynamic Imports + +To dynamically import a component (also known as lazy-loading a component) all you need to do is add the `Lazy` prefix to the component name. + +```html{}[layouts/default.vue] + +``` + +This is particularly useful if the component is not always needed. By using the `Lazy` prefix you can delay loading the component code until the right moment, which can be helpful for optimizing your JavaScript bundle size. + +```html{}[pages/index.vue] + + + +``` + +## Library Authors + +Making Vue component libraries with automatic tree-shaking and component registration is super easy ✨ + +You can use the `components:dirs` hook to easily extend the directory list without requiring user configuration in your Nuxt module. + +Imagine a directory structure like this: + +```bash +| 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:dirs` hook: + +```js +import { join } from 'pathe' + +export default defineNuxtModule({ + hooks: { + '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`: + +```js +export default { + buildModules: ['awesome-ui/nuxt'] +} +``` + +And directly use the module components (prefixed with `awesome-`), our `pages/index.vue`: + +```vue + +``` + +It will automatically import the components only if used and also support HMR when updating your components in `node_modules/awesome-ui/components/`. +