diff --git a/docs/3.api/4.advanced/2.kit.md b/docs/3.api/4.advanced/2.kit.md index accdb1bbb1..e3e403f9cd 100644 --- a/docs/3.api/4.advanced/2.kit.md +++ b/docs/3.api/4.advanced/2.kit.md @@ -400,9 +400,312 @@ Nuxt instance. If not provided, it will be retrieved from the context via `useNu [source code](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/imports.ts) -- `addImports(imports)` -- `addImportsDir(importDirs, { prepend? })` -- `addImportsSources(importSources)` +### `addImports` + +Add imports to the Nuxt application. It makes your imports available in the Nuxt application without the need to import them manually. + +#### Type + +```ts +function addImports (imports: Import | Import[]): void + +interface Import { + from: string + priority?: number + disabled?: boolean + meta?: { + description?: string + docsUrl?: string + [key: string]: any + } + type?: boolean + typeFrom?: string + name: string + as?: string +} +``` + +#### Parameters + +##### `imports` + +**Type**: `Import | Import[]` + +**Required**: `true` + +An object or an array of objects with the following properties: + +- `from` (required) + + **Type**: `string` + + Module specifier to import from. + +- `priority` (optional) + + **Type**: `number` + + **Default**: `1` + + Priority of the import, if multiple imports have the same name, the one with the highest priority will be used. + +- `disabled` (optional) + + **Type**: `boolean` + + If this import is disabled. + +- `meta` (optional) + + **Type**: `object` + + Metadata of the import. + +- `meta.description` (optional) + + **Type**: `string` + + Short description of the import. + +- `meta.docsUrl` (optional) + + **Type**: `string` + + URL to the documentation. + +- `meta[key]` (optional) + + **Type**: `any` + + Additional metadata. + +- `type` (optional) + + **Type**: `boolean` + + If this import is a pure type import. + +- `typeFrom` (optional) + + **Type**: `string` + + Using this as the from when generating type declarations. + +- `name` (required) + + **Type**: `string` + + Import name to be detected. + +- `as` (optional) + + **Type**: `string` + + Import as this name. + +#### Examples + +```ts +import { defineNuxtModule, addImports, createResolver } from '@nuxt/kit' + +// creds: https://github.com/pi0/storyblok-nuxt +export default defineNuxtModule({ + setup(options, nuxt) { + const names = [ + "useStoryblok", + "useStoryblokApi", + "useStoryblokBridge", + "renderRichText", + "RichTextSchema" + ]; + + names.forEach((name) => + addImports({ name, as: name, from: "@storyblok/vue" }) + ); + } +}) +``` + +### `addImportsDir` + +Add imports from a directory to the Nuxt application. It will automatically import all files from the directory and make them available in the Nuxt application without the need to import them manually. + +#### Type + +```ts +function addImportsDir (dirs: string | string[], opts?: { prepend?: boolean }) +``` + +#### Parameters + +##### `dirs` + +**Type**: `string | string[]` + +**Required**: `true` + +A string or an array of strings with the path to the directory to import from. + +##### `opts` + +**Type**: `{ prepend?: boolean }` + +**Default**: `{}` + +Options to pass to the import. If `prepend` is set to `true`, the imports will be prepended to the list of imports. + +#### Examples + +```ts +import { defineNuxtModule, addImportsDir, createResolver } from '@nuxt/kit' + +// creds: https://github.com/vueuse/motion/tree/main/src/nuxt +export default defineNuxtModule({ + meta: { + name: '@vueuse/motion', + configKey: 'motion', + }, + defaults: {}, + setup(options, nuxt) { + const { resolve } = createResolver(import.meta.url) + addImportsDir(resolve('./runtime/composables')) + }, +}) +``` + +### `addImportsSources` + +Add listed imports to the Nuxt application. + +#### Type + +```ts +function addImportsSources (importSources: ImportSource | ImportSource[]) + +interface Import { + from: string + priority?: number + disabled?: boolean + meta?: { + description?: string + docsUrl?: string + [key: string]: any + } + type?: boolean + typeFrom?: string + name: string + as?: string +} + +interface ImportSource extends Import { + imports: (PresetImport | ImportSource)[] +} + +type PresetImport = Omit | string | [name: string, as?: string, from?: string] +``` + +#### Parameters + +##### `importSources` + +**Type**: `ImportSource | ImportSource[]` + +**Required**: `true` + +An object or an array of objects with the following properties: + +- `imports` (required) + + **Type**: `PresetImport | ImportSource[]` + + **Required**: `true` + + An object or an array of objects, which can be import names, import objects or import sources. + +- `from` (required) + + **Type**: `string` + + Module specifier to import from. + +- `priority` (optional) + + **Type**: `number` + + **Default**: `1` + + Priority of the import, if multiple imports have the same name, the one with the highest priority will be used. + +- `disabled` (optional) + + **Type**: `boolean` + + If this import is disabled. + +- `meta` (optional) + + **Type**: `object` + + Metadata of the import. + +- `meta.description` (optional) + + **Type**: `string` + + Short description of the import. + +- `meta.docsUrl` (optional) + + **Type**: `string` + + URL to the documentation. + +- `meta[key]` (optional) + + **Type**: `any` + + Additional metadata. + +- `type` (optional) + + **Type**: `boolean` + + If this import is a pure type import. + +- `typeFrom` (optional) + + **Type**: `string` + + Using this as the from when generating type declarations. + +- `name` (required) + + **Type**: `string` + + Import name to be detected. + +- `as` (optional) + + **Type**: `string` + + Import as this name. + +#### Examples + +```ts +import { defineNuxtModule, addImportsSources } from '@nuxt/kit' + +// creds: https://github.com/elk-zone/elk +export default defineNuxtModule({ + setup() { + // add imports from h3 to make them autoimported + addImportsSources({ + from: 'h3', + imports: ['defineEventHandler', 'getQuery', 'getRouterParams', 'readBody', 'sendRedirect'] as Array, + }) + } +}) +``` ## Components