From beef86152199b3b050875e31aedbb1dd4caa6072 Mon Sep 17 00:00:00 2001 From: Andrey Yolkin Date: Fri, 4 Aug 2023 17:32:52 +0300 Subject: [PATCH] feat(docs): describe components utilities --- docs/3.api/4.advanced/2.kit.md | 275 ++++++++++++++++++++++++++++++++- 1 file changed, 273 insertions(+), 2 deletions(-) diff --git a/docs/3.api/4.advanced/2.kit.md b/docs/3.api/4.advanced/2.kit.md index e3e403f9cd..10e00b8e68 100644 --- a/docs/3.api/4.advanced/2.kit.md +++ b/docs/3.api/4.advanced/2.kit.md @@ -711,8 +711,279 @@ export default defineNuxtModule({ [source code](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/components.ts) -- `addComponentsDir(dir)` -- `addComponent(componentObject)` +### `addComponentsDir` + +Register a directory to be scanned for components and imported only when used. Keep in mind, that this does not register components globally, until you specify `global: true` option. + +#### Type + +```ts +async function addComponentsDir (dir: ComponentsDir): void + +interface ComponentsDir { + path: string + pattern?: string | string[] + ignore?: string[] + prefix?: string + pathPrefix?: boolean + enabled?: boolean + prefetch?: boolean + preload?: boolean + isAsync?: boolean + extendComponent?: (component: Component) => Promise | (Component | void) + global?: boolean + island?: boolean + watch?: boolean + extensions?: string[] + transpile?: 'auto' | boolean +} + +interface Component { + pascalName: string + kebabName: string + export: string + filePath: string + shortPath: string + chunkName: string + prefetch: boolean + preload: boolean + global?: boolean + island?: boolean + mode?: 'client' | 'server' | 'all' + priority?: number +} +``` + +#### Parameters + +##### `dir` + +**Type**: `ComponentsDir` + +**Required**: `true` + +An object with the following properties: + +- `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 project or directly use an npm package path similar to require. + +- `pattern` (optional) + + **Type**: `string | string[]` + + Accept Pattern that will be run against specified path. + +- `ignore` (optional) + + **Type**: `string[]` + + Ignore patterns that will be run against specified path. + +- `prefix` (optional) + + **Type**: `string` + + Prefix all matched components with this string. + +- `pathPrefix` (optional) + + **Type**: `boolean` + + Prefix component name by its path. + +- `enabled` (optional) + + **Type**: `boolean` + + Ignore scanning this directory if set to `true`. + +- `prefetch` (optional) + + **Type**: `boolean` + + These properties (prefetch/preload) are used in production to configure how components with Lazy prefix are handled by webpack via its magic comments. + Learn more on [webpack documentation](https://webpack.js.org/api/module-methods/#magic-comments) + +- `preload` (optional) + + **Type**: `boolean` + + These properties (prefetch/preload) are used in production to configure how components with Lazy prefix are handled by webpack via its magic comments. + Learn more on [webpack documentation](https://webpack.js.org/api/module-methods/#magic-comments) + +- `isAsync` (optional) + + **Type**: `boolean` + + This flag indicates, component should be loaded async (with a separate chunk) regardless of using Lazy prefix or not. + +- `extendComponent` (optional) + + **Type**: `(component: Component) => Promise | (Component | void)` + + A function that will be called for each component found in the directory. It accepts a component object and should return a component object or a promise that resolves to a component object. + +- `global` (optional) + + **Type**: `boolean` + + **Default**: `false` + + If enabled, registers components to be globally available. + +- `island` (optional) + + **Type**: `boolean` + + If enabled, registers components as islands. + +- `watch` (optional) + + **Type**: `boolean` + + Watch specified path for changes, including file additions and file deletions. + +- `extensions` (optional) + + **Type**: `string[]` + + Extensions supported by Nuxt builder. + +- `transpile` (optional) + + **Type**: `'auto' | boolean` + + Transpile specified path using build.transpile. If set to `'auto'`, it will set `transpile: true` if `node_modules/` is in path. + +## `addComponent` + +Register a component to be automatically imported. + +#### Type + +```ts +async function addComponent (opts: AddComponentOptions): void + +interface AddComponentOptions { + name: string, + filePath: string, + pascalName?: string, + kebabName?: string, + export?: string, + shortPath?: string, + chunkName?: string, + prefetch?: boolean, + preload?: boolean, + global?: boolean, + island?: boolean, + mode?: 'client' | 'server' | 'all', + priority?: number, +} +``` + +#### Parameters + +##### `opts` + +**Type**: `AddComponentOptions` + +**Required**: `true` + +An object with the following properties: + +- `name` (required) + + **Type**: `string` + + Component name. + +- `filePath` (required) + + **Type**: `string` + + Path to the component. + +- `pascalName` (optional) + + **Type**: `pascalCase(opts.name)` + + Pascal case component name. If not provided, it will be generated from the component name. + +- `kebabName` (optional) + + **Type**: `kebabCase(opts.name)` + + Kebab case component name. If not provided, it will be generated from the component name. + +- `export` (optional) + + **Type**: `string` + + **Default**: `'default'` + + Specify named or default export. If not provided, it will be set to `'default'`. + +- `shortPath` (optional) + + **Type**: `string` + + Short path to the component. If not provided, it will be generated from the component path. + +- `chunkName` (optional) + + **Type**: `string` + + **Default**: `'components/' + kebabCase(opts.name)` + + Chunk name for the component. If not provided, it will be generated from the component name. + +- `prefetch` (optional) + + **Type**: `boolean` + + These properties (prefetch/preload) are used in production to configure how components with Lazy prefix are handled by webpack via its magic comments. + Learn more on [webpack documentation](https://webpack.js.org/api/module-methods/#magic-comments) + +- `preload` (optional) + + **Type**: `boolean` + + These properties (prefetch/preload) are used in production to configure how components with Lazy prefix are handled by webpack via its magic comments. + Learn more on [webpack documentation](https://webpack.js.org/api/module-methods/#magic-comments) + +- `global` (optional) + + **Type**: `boolean` + + **Default**: `false` + + If enabled, registers component to be globally available. + +- `island` (optional) + + **Type**: `boolean` + + If enabled, registers component as island. You can read more about islands in [](/docs/api/components/nuxt-island#nuxtisland) component description. + +- `mode` (optional) + + **Type**: `'client' | 'server' | 'all'` + + **Default**: `'all'` + + This options indicates if component should render on client, server or both. By default, it will render on both client and server. + +- `priority` (optional) + + **Type**: `number` + + **Default**: `1` + + Priority of the component, if multiple components have the same name, the one with the highest priority will be used. ## Context