@nuxt/docs 0.0.0 → 3.17.0

package/3.api/5.kit/3.compatibility.md

@@ -0,0 +1,230 @@
+---
+title: "Compatibility"
+description: Nuxt Kit provides a set of utilities to help you check the compatibility of your modules with different Nuxt versions.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/compatibility.ts
+    size: xs
+---
+
+Nuxt Kit utilities can be used in Nuxt 3, Nuxt 2 with Bridge and even Nuxt 2 without Bridge. To make sure your module is compatible with all versions, you can use the `checkNuxtCompatibility`, `assertNuxtCompatibility` and `hasNuxtCompatibility` functions. They will check if the current Nuxt version meets the constraints you provide. Also you can use `isNuxt2`, `isNuxt3` and `getNuxtVersion` functions for more granular checks.
+
+## `checkNuxtCompatibility`
+
+Checks if constraints are met for the current Nuxt version. If not, returns an array of messages. Nuxt 2 version also checks for `bridge` support.
+
+### Type
+
+```ts
+async function checkNuxtCompatibility(
+  constraints: NuxtCompatibility,
+  nuxt?: Nuxt
+): Promise<NuxtCompatibilityIssues>;
+
+interface NuxtCompatibility {
+  nuxt?: string;
+  bridge?: boolean;
+  builder?: {
+    // Set `false` if your module is not compatible with a builder
+    // or a semver-compatible string version constraint
+    vite?: false | string;
+    webpack?: false | string;
+  };
+}
+
+interface NuxtCompatibilityIssue {
+  name: string;
+  message: string;
+}
+
+interface NuxtCompatibilityIssues extends Array<NuxtCompatibilityIssue> {
+  toString(): string;
+}
+```
+
+### Parameters
+
+#### `constraints`
+
+**Type**: `NuxtCompatibility`
+
+**Default**: `{}`
+
+Constraints to check for. It accepts the following properties:
+
+- `nuxt` (optional)
+
+  **Type**: `string`
+
+  Nuxt version in semver format. Versions may be defined in Node.js way, for example: `>=2.15.0 <3.0.0`.
+
+- `bridge` (optional)
+
+  **Type**: `boolean`
+
+  If set to `true`, it will check if the current Nuxt version supports `bridge`.
+
+#### `nuxt`
+
+**Type**: `Nuxt`
+
+**Default**: `useNuxt()`
+
+Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
+
+## `assertNuxtCompatibility`
+
+Asserts that constraints are met for the current Nuxt version. If not, throws an error with the list of issues as string.
+
+### Type
+
+```ts
+async function assertNuxtCompatibility(
+  constraints: NuxtCompatibility,
+  nuxt?: Nuxt
+): Promise<true>;
+
+interface NuxtCompatibility {
+  nuxt?: string;
+  bridge?: boolean;
+}
+```
+
+### Parameters
+
+#### `constraints`
+
+**Type**: `NuxtCompatibility`
+
+**Default**: `{}`
+
+Constraints to check for. It accepts the following properties:
+
+- `nuxt` (optional)
+
+  **Type**: `string`
+
+  Nuxt version in semver format. Versions may be defined in Node.js way, for example: `>=2.15.0 <3.0.0`.
+
+- `bridge` (optional)
+
+  **Type**: `boolean`
+
+  If set to `true`, it will check if the current Nuxt version supports `bridge`.
+
+#### `nuxt`
+
+**Type**: `Nuxt`
+
+**Default**: `useNuxt()`
+
+Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
+
+## `hasNuxtCompatibility`
+
+Checks if constraints are met for the current Nuxt version. Return `true` if all constraints are met, otherwise returns `false`. Nuxt 2 version also checks for `bridge` support.
+
+### Type
+
+```ts
+async function hasNuxtCompatibility(
+  constraints: NuxtCompatibility,
+  nuxt?: Nuxt
+): Promise<boolean>;
+
+interface NuxtCompatibility {
+  nuxt?: string;
+  bridge?: boolean;
+}
+```
+
+### Parameters
+
+#### `constraints`
+
+**Type**: `NuxtCompatibility`
+
+**Default**: `{}`
+
+Constraints to check for. It accepts the following properties:
+
+- `nuxt` (optional)
+
+  **Type**: `string`
+
+  Nuxt version in semver format. Versions may be defined in Node.js way, for example: `>=2.15.0 <3.0.0`.
+
+- `bridge` (optional)
+
+  **Type**: `boolean`
+
+  If set to `true`, it will check if the current Nuxt version supports `bridge`.
+
+#### `nuxt`
+
+**Type**: `Nuxt`
+
+**Default**: `useNuxt()`
+
+Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
+
+## `isNuxt2`
+
+Checks if the current Nuxt version is 2.x.
+
+### Type
+
+```ts
+function isNuxt2(nuxt?: Nuxt): boolean;
+```
+
+### Parameters
+
+#### `nuxt`
+
+**Type**: `Nuxt`
+
+**Default**: `useNuxt()`
+
+Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
+
+## `isNuxt3`
+
+Checks if the current Nuxt version is 3.x.
+
+### Type
+
+```ts
+function isNuxt3(nuxt?: Nuxt): boolean;
+```
+
+### Parameters
+
+#### `nuxt`
+
+**Type**: `Nuxt`
+
+**Default**: `useNuxt()`
+
+Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.
+
+## `getNuxtVersion`
+
+Returns the current Nuxt version.
+
+### Type
+
+```ts
+function getNuxtVersion(nuxt?: Nuxt): string;
+```
+
+### Parameters
+
+#### `nuxt`
+
+**Type**: `Nuxt`
+
+**Default**: `useNuxt()`
+
+Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.

package/3.api/5.kit/4.autoimports.md

@@ -0,0 +1,144 @@
+---
+title: "Auto-imports"
+description: Nuxt Kit provides a set of utilities to help you work with auto-imports. These functions allow you to register your own utils, composables and Vue APIs.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/imports.ts
+    size: xs
+---
+
+Nuxt auto-imports helper functions, composables and Vue APIs to use across your application without explicitly importing them. Based on the directory structure, every Nuxt application can also use auto-imports for its own composables and plugins.
+
+With Nuxt Kit you can also add your own auto-imports. `addImports` and `addImportsDir` allow you to add imports to the Nuxt application. `addImportsSources` allows you to add listed imports from 3rd party packages to the Nuxt application.
+
+These utilities are powered by [`unimport`](https://github.com/unjs/unimport), which provides the underlying auto-import mechanism used in Nuxt.
+
+::note
+These functions are designed for registering your own utils, composables and Vue APIs. For pages, components and plugins, please refer to the specific sections: [Pages](/docs/api/kit/pages), [Components](/docs/api/kit/components), [Plugins](/docs/api/kit/plugins).
+::
+
+::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/expanding-nuxt-s-auto-imports?friend=nuxt" target="_blank"}
+Watch Vue School video about Auto-imports Nuxt Kit utilities.
+::
+
+## `addImports`
+
+Add imports to the Nuxt application. It makes your imports available in the Nuxt application without the need to import them manually.
+
+### Usage
+
+```ts twoslash
+import { defineNuxtModule, addImports } from "@nuxt/kit";
+
+export default defineNuxtModule({
+  setup(options, nuxt) {
+    const names = [
+      "useStoryblok",
+      "useStoryblokApi",
+      "useStoryblokBridge",
+      "renderRichText",
+      "RichTextSchema"
+    ];
+
+    names.forEach((name) =>
+      addImports({ name, as: name, from: "@storyblok/vue" })
+    );
+  }
+})
+```
+
+### Type
+
+```ts
+function addImports (imports: Import | Import[]): void
+```
+
+### Parameters
+
+`imports`: An object or an array of objects with the following properties:
+
+| Prop               | Type                         | Required | Description                                                                                                     |
+| ------------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `name`             | `string`                     | `true`   | Import name to be detected.                                                                                     |
+| `from`             | `string`                     | `true`   | Module specifier to import from.                                                                                |
+| `priority`         | `number`                     | `false`  | Priority of the import; if multiple imports have the same name, the one with the highest priority will be used. |
+| `disabled`         | `boolean`                    | `false`  | If this import is disabled.                                                                                     |
+| `meta`             | `Record<string, any>`        | `false`  | Metadata of the import.                                                                                         |
+| `type`             | `boolean`                    | `false`  | If this import is a pure type import.                                                                           |
+| `typeFrom`         | `string`                     | `false`  | Use this as the `from` value when generating type declarations.                                                 |
+| `as`               | `string`                     | `false`  | Import as this name.                                                                                            |
+
+## `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.
+
+### Usage
+
+```ts twoslash
+import { defineNuxtModule, addImportsDir, createResolver } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: '@vueuse/motion',
+    configKey: 'motion',
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+    addImportsDir(resolver.resolve('./runtime/composables'))
+  },
+})
+```
+
+### Type
+
+```ts
+function addImportsDir (dirs: string | string[], options?: { prepend?: boolean }): void
+```
+
+### Parameters
+
+| Prop               | Type                         | Required | Description                                                                                                     |
+| ------------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `dirs`             | `string \| string[]`{lang="ts"}          | `true`   | A string or an array of strings with the path to the directory to import from.                                 |
+| `options`          | `{ prepend?: boolean }`{lang="ts"}      | `false`  | Options to pass to the import. If `prepend` is set to `true`, the imports will be prepended to the list of imports. |
+
+## `addImportsSources`
+
+Add listed imports to the Nuxt application.
+
+### Usage
+
+```ts twoslash
+import { defineNuxtModule, addImportsSources } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup() {
+    addImportsSources({
+      from: 'h3',
+      imports: [
+        'defineEventHandler',
+        'getQuery',
+        'getRouterParams',
+        'readBody',
+        'sendRedirect'
+      ],
+    })
+  }
+})
+```
+
+### Type
+
+```ts
+function addImportsSources (importSources: ImportSource | ImportSource[]): void
+```
+
+### Parameters
+
+**importSources**: An object or an array of objects with the following properties:
+
+| Prop               | Type                         | Required | Description                                                                                                     |
+| ------------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `from`             | `string`                     | `true`   | Module specifier to import from.                                                                                |
+| `imports`          | `PresetImport \| ImportSource[]`{lang="ts"} | `true`   | An object or an array of objects, which can be import names, import objects or import sources.                  |

package/3.api/5.kit/5.components.md

@@ -0,0 +1,127 @@
+---
+title: "Components"
+description: Nuxt Kit provides a set of utilities to help you work with components. You can register components globally or locally, and also add directories to be scanned for components.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/components.ts
+    size: xs
+---
+
+Components are the building blocks of your Nuxt application. They are reusable Vue instances that can be used to create a user interface. In Nuxt, components from the components directory are automatically imported by default. However, if you need to import components from an alternative directory or wish to selectively import them as needed, `@nuxt/kit` provides the `addComponentsDir` and `addComponent` methods. These utils allow you to customize the component configuration to better suit your needs.
+
+::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/injecting-components-and-component-directories?friend=nuxt" target="_blank"}
+Watch Vue School video about injecting components.
+::
+
+## `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.
+
+### Usage
+
+```ts
+export default defineNuxtModule({
+  meta: {
+    name: '@nuxt/ui',
+    configKey: 'ui',
+  },
+  setup() {
+    addComponentsDir({
+      path: resolve('./runtime/components'),
+      prefix: 'U',
+      pathPrefix: false
+    })
+  }
+})
+```
+
+### Type
+
+```ts
+function addComponentsDir (dir: ComponentsDir, opts: { prepend?: boolean } = {}): void
+```
+
+### Parameters
+
+`dir` An object with the following properties:
+
+| Prop               | Type                         | Required | Description                                                                                                     |
+| ------------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `path`             | `string`                     | `true`   | 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`          | `string \| string[]`{lang="ts"}          | `false`  | Accept Pattern that will be run against specified path.                                                         |
+| `ignore`           | `string[]`                   | `false`  | Ignore patterns that will be run against specified path.                                                        |
+| `prefix`           | `string`                     | `false`  | Prefix all matched components with this string.                                                                |
+| `pathPrefix`       | `boolean`                    | `false`  | Prefix component name by its path.                                                                              |
+| `enabled`          | `boolean`                    | `false`  | Ignore scanning this directory if set to `true`.                                                                |
+| `prefetch`         | `boolean`                    | `false`  | 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`          | `boolean`                    | `false`  | 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`          | `boolean`                    | `false`  | This flag indicates, component should be loaded async (with a separate chunk) regardless of using Lazy prefix or not. |
+| `extendComponent`  | `(component: Component) => Promise<Component \| void> \| (Component \| void)`{lang="ts"} | `false`  | 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`           | `boolean`                    | `false`  | If enabled, registers components to be globally available.                                                      |
+| `island`           | `boolean`                    | `false`  | If enabled, registers components as islands. You can read more about islands in [`<NuxtIsland/>`](/docs/api/components/nuxt-island#nuxtisland) component description. |
+| `watch`            | `boolean`                    | `false`  | Watch specified path for changes, including file additions and file deletions.                                  |
+| `extensions`       | `string[]`                   | `false`  | Extensions supported by Nuxt builder.                                                                          |
+| `transpile`        | `'auto' \| boolean`{lang="ts"} | `false`  | Transpile specified path using build.transpile. If set to `'auto'`, it will set `transpile: true` if `node_modules/` is in path. |
+
+`opts`
+
+| Prop               | Type                         | Required | Description                                                                                                     |
+| ------------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `prepend`          | `boolean`                    | `false`  | If set to `true`, the directory will be prepended to the array with `unshift()` instead of `push()`.            |
+
+## `addComponent`
+
+Register a component to be automatically imported.
+
+### Usage
+
+```ts
+import { defineNuxtModule, createResolver, addComponent } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: '@nuxt/image',
+    configKey: 'image',
+  },
+  async setup() {
+    const resolver = createResolver(import.meta.url)
+
+    addComponent({
+      name: 'NuxtImg',
+      filePath: resolver.resolve('./runtime/components/NuxtImg.vue'),
+    })
+
+    addComponent({
+      name: 'NuxtPicture',
+      filePath: resolver.resolve('./runtime/components/NuxtPicture.vue'),
+    })
+  },
+})
+```
+
+### Type
+
+```ts
+function addComponent (options: AddComponentOptions): void
+```
+
+### Parameters
+
+`options`: An object with the following properties:
+
+| Prop               | Type                         | Required | Description                                                                                                     |
+| ------------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |  
+| `name`             | `string`                     | `true`   | Component name.                                                                                                 |
+| `filePath`         | `string`                     | `true`   | Path to the component.                                                                                          |
+| `pascalName`       | `string`                     | `false`  | Pascal case component name. If not provided, it will be generated from the component name.                      |
+| `kebabName`        | `string`                     | `false`  | Kebab case component name. If not provided, it will be generated from the component name.                       |
+| `export`           | `string`                     | `false`  | Specify named or default export. If not provided, it will be set to `'default'`.                                 |
+| `shortPath`        | `string`                     | `false`  | Short path to the component. If not provided, it will be generated from the component path.                      |
+| `chunkName`        | `string`                     | `false`  | Chunk name for the component. If not provided, it will be generated from the component name.                     |
+| `prefetch`         | `boolean`                    | `false`  | 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`          | `boolean`                    | `false`  | 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`           | `boolean`                    | `false`  | If enabled, registers component to be globally available.                                                        |
+| `island`           | `boolean`                    | `false`  | If enabled, registers component as island. You can read more about islands in [`<NuxtIsland/>`](/docs/api/components/nuxt-island#nuxtisland) component description. |
+| `mode`             | `'client' \| 'server' \| 'all'`{lang="ts"} | `false`  | This options indicates if component should render on client, server or both. By default, it will render on both client and server. |
+| `priority`         | `number`                     | `false`  | Priority of the component, if multiple components have the same name, the one with the highest priority will be used. |

package/3.api/5.kit/6.context.md

@@ -0,0 +1,130 @@
+---
+title: "Context"
+description: Nuxt Kit provides a set of utilities to help you work with context.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/context.ts
+    size: xs
+---
+
+Nuxt modules allow you to enhance Nuxt's capabilities. They offer a structured way to keep your code organized and modular. If you're looking to break down your module into smaller components, Nuxt offers the `useNuxt` and `tryUseNuxt` functions. These functions enable you to conveniently access the Nuxt instance from the context without having to pass it as argument.
+
+::note
+When you're working with the `setup` function in Nuxt modules, Nuxt is already provided as the second argument. This means you can directly utilize it without needing to call `useNuxt()`. You can look at [Nuxt Site Config](https://github.com/harlan-zw/nuxt-site-config) as an example of usage.
+::
+
+## `useNuxt`
+
+Get the Nuxt instance from the context. It will throw an error if Nuxt is not available.
+
+### Type
+
+```ts
+function useNuxt(): Nuxt
+
+interface Nuxt {
+  options: NuxtOptions
+  hooks: Hookable<NuxtHooks>
+  hook: Nuxt['hooks']['hook']
+  callHook: Nuxt['hooks']['callHook']
+  addHooks: Nuxt['hooks']['addHooks']
+  ready: () => Promise<void>
+  close: () => Promise<void>
+  server?: any
+  vfs: Record<string, string>
+  apps: Record<string, NuxtApp>
+}
+```
+
+### Examples
+
+::code-group
+
+```ts [setupTranspilation.ts]
+// https://github.com/Lexpeartha/nuxt-xstate/blob/main/src/parts/transpile.ts
+import { useNuxt } from '@nuxt/kit'
+
+export const setupTranspilation = () => {
+  const nuxt = useNuxt()
+
+  nuxt.options.build.transpile = nuxt.options.build.transpile || []
+
+  if (nuxt.options.builder === '@nuxt/webpack-builder') {
+    nuxt.options.build.transpile.push(
+      'xstate',
+    )
+  }
+}
+```
+
+```ts [module.ts]
+import { useNuxt } from '@nuxt/kit'
+import { setupTranspilation } from './setupTranspilation'
+
+export default defineNuxtModule({
+  setup() {
+    setupTranspilation()
+  }
+})
+```
+
+::
+
+## `tryUseNuxt`
+
+Get the Nuxt instance from the context. It will return `null` if Nuxt is not available.
+
+### Type
+
+```ts
+function tryUseNuxt(): Nuxt | null
+
+interface Nuxt {
+  options: NuxtOptions
+  hooks: Hookable<NuxtHooks>
+  hook: Nuxt['hooks']['hook']
+  callHook: Nuxt['hooks']['callHook']
+  addHooks: Nuxt['hooks']['addHooks']
+  ready: () => Promise<void>
+  close: () => Promise<void>
+  server?: any
+  vfs: Record<string, string>
+  apps: Record<string, NuxtApp>
+}
+```
+
+### Examples
+
+::code-group
+
+```ts [requireSiteConfig.ts]
+// https://github.com/harlan-zw/nuxt-site-config/blob/main/test/assertions.test.ts
+import { tryUseNuxt } from '@nuxt/kit'
+
+interface SiteConfig {
+  title: string
+}
+
+export const requireSiteConfig = (): SiteConfig => {
+  const nuxt = tryUseNuxt()
+  if (!nuxt) {
+    return { title: null }
+  }
+  return nuxt.options.siteConfig
+}
+```
+
+```ts [module.ts]
+import { useNuxt } from '@nuxt/kit'
+import { requireSiteConfig } from './requireSiteConfig'
+
+export default defineNuxtModule({
+  setup(_, nuxt) {
+    const config = requireSiteConfig()
+    nuxt.options.app.head.title = config.title
+  }
+})
+```
+
+::