@nuxt/docs 3.17.0 → 3.17.2

package/3.api/5.kit/12.resolving.md

@@ -14,58 +14,42 @@ Sometimes you need to resolve a paths: relative to the current module, with unkn
 
 Resolves full path to a file or directory respecting Nuxt alias and extensions options. If path could not be resolved, normalized input path will be returned.
 
-### Type
+### Usage
 
 ```ts
-async function resolvePath (path: string, options?: ResolvePathOptions): Promise<string>
-```
-
-### Parameters
-
-#### `path`
-
-**Type**: `string`
-
-**Required**: `true`
-
-Path to resolve.
-
-#### `options`
-
-**Type**: `ResolvePathOptions`
-
-**Default**: `{}`
-
-Options to pass to the resolver. This object can have the following properties:
-
-- `cwd` (optional)
-
-  **Type**: `string`
-
-  **Default**: `process.cwd()`
-
-  Current working directory.
-
-- `alias` (optional)
+import { defineNuxtModule, resolvePath } from '@nuxt/kit'
 
-  **Type**: `Record<string, string>`
+export default defineNuxtModule({
+  async setup () {
+    const entrypoint = await resolvePath('@unhead/vue')
+    console.log(`Unhead entrypoint is ${entrypoint}`)
+  },
+})
+```
 
-  **Default**: `{}`
+### Type
 
-  Alias map.
+```ts
+function resolvePath (path: string, options?: ResolvePathOptions): Promise<string>
+```
 
-- `extensions` (optional)
+### Parameters
 
-  **Type**: `string[]`
+**`path`**: A path to resolve.
 
-  **Default**: `['.js', '.mjs', '.ts', '.jsx', '.tsx', '.json']`
+**`options`**: Options to pass to the resolver. This object can have the following properties:
 
-  Extensions to try.
+| Property             | Type                                | Required | Description                                                                                                                  |
+| -------------------- | ----------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `cwd`                | `string`                            | `false`  | Base for resolving paths from. Default is Nuxt rootDir.                                                                      |
+| `alias`              | `Record<string, string>`{lang="ts"} | `false`  | An object of aliases. Default is Nuxt configured aliases.                                                                    |
+| `extensions`         | `string[]`                          | `false`  | The file extensions to try. Default is Nuxt configured extensions.                                                           |
+| `virtual`            | `boolean`                           | `false`  | Whether to resolve files that exist in the Nuxt VFS (for example, as a Nuxt template).                                       |
+| `fallbackToOriginal` | `boolean`                           | `false`  | Whether to fallback to the original path if the resolved path does not exist instead of returning the normalized input path. |
 
 ### Examples
 
 ```ts
-// https://github.com/P4sca1/nuxt-headlessui
 import { defineNuxtModule, resolvePath } from '@nuxt/kit'
 import { join } from 'pathe'
 
@@ -79,8 +63,8 @@ const headlessComponents: ComponentGroup[] = [
       'ComboboxButton',
       'ComboboxInput',
       'ComboboxOptions',
-      'ComboboxOption'
-    ]
+      'ComboboxOption',
+    ],
   },
 ]
 
@@ -90,7 +74,7 @@ export default defineNuxtModule({
     configKey: 'headlessui',
   },
   defaults: {
-    prefix: 'Headless'
+    prefix: 'Headless',
   },
   async setup (options) {
     const entrypoint = await resolvePath('@headlessui/vue')
@@ -104,12 +88,12 @@ export default defineNuxtModule({
             export: e,
             filePath: join(root, group.relativePath),
             chunkName: group.chunkName,
-            mode: 'all'
-          }
+            mode: 'all',
+          },
         )
       }
     }
-  }
+  },
 })
 ```
 
@@ -125,87 +109,50 @@ function resolveAlias (path: string, alias?: Record<string, string>): string
 
 ### Parameters
 
-#### `path`
-
-**Type**: `string`
+**`path`**: A path to resolve.
 
-**Required**: `true`
-
-Path to resolve.
-
-#### `alias`
-
-**Type**: `Record<string, string>`
-
-**Default**: `{}`
-
-Alias map. If not provided, it will be read from `nuxt.options.alias`.
+**`alias`**: An object of aliases. If not provided, it will be read from `nuxt.options.alias`.
 
 ## `findPath`
 
 Try to resolve first existing file in given paths.
 
-### Type
+### Usage
 
 ```ts
-async function findPath (paths: string | string[], options?: ResolvePathOptions, pathType: 'file' | 'dir'): Promise<string | null>
+import { defineNuxtModule, findPath } from '@nuxt/kit'
+import { join } from 'pathe'
 
-interface ResolvePathOptions {
-  cwd?: string
-  alias?: Record<string, string>
-  extensions?: string[]
-}
+export default defineNuxtModule({
+  async setup (_, nuxt) {
+    // Resolve main (app.vue)
+    const mainComponent = await findPath([
+      join(nuxt.options.srcDir, 'App'),
+      join(nuxt.options.srcDir, 'app'),
+    ])
+  },
+})
 ```
 
-### Parameters
-
-#### `paths`
-
-**Type**: `string | string[]`
-
-**Required**: `true`
-
-A path or an array of paths to resolve.
-
-#### `options`
-
-**Type**: `ResolvePathOptions`
-
-**Default**: `{}`
-
-Options to pass to the resolver. This object can have the following properties:
-
-- `cwd` (optional)
-
-  **Type**: `string`
-
-  **Default**: `process.cwd()`
-
-  Current working directory.
-
-- `alias` (optional)
-
-  **Type**: `Record<string, string>`
-
-  **Default**: `{}`
-
-  Alias map.
-
-- `extensions` (optional)
-
-  **Type**: `string[]`
-
-  **Default**: `['.js', '.mjs', '.ts', '.jsx', '.tsx', '.json']`
+### Type
 
-  Extensions to try.
+```ts
+function findPath (paths: string | string[], options?: ResolvePathOptions, pathType: 'file' | 'dir'): Promise<string | null>
+```
 
-#### `pathType`
+### Parameters
 
-**Type**: `'file' | 'dir'`
+**`paths`**: A path or an array of paths to resolve.
 
-**Default**: `'file'`
+**`options`**: Options to pass to the resolver. This object can have the following properties:
 
-Type of path to resolve. If set to `'file'`, the function will try to resolve a file. If set to `'dir'`, the function will try to resolve a directory.
+| Property             | Type                                | Required | Description                                                                                                                  |
+| -------------------- | ----------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `cwd`                | `string`                            | `false`  | Base for resolving paths from. Default is Nuxt rootDir.                                                                      |
+| `alias`              | `Record<string, string>`{lang="ts"} | `false`  | An object of aliases. Default is Nuxt configured aliases.                                                                    |
+| `extensions`         | `string[]`                          | `false`  | The file extensions to try. Default is Nuxt configured extensions.                                                           |
+| `virtual`            | `boolean`                           | `false`  | Whether to resolve files that exist in the Nuxt VFS (for example, as a Nuxt template).                                       |
+| `fallbackToOriginal` | `boolean`                           | `false`  | Whether to fallback to the original path if the resolved path does not exist instead of returning the normalized input path. |
 
 ## `createResolver`
 
@@ -215,45 +162,44 @@ Creates resolver relative to base path.
 Watch Vue School video about createResolver.
 ::
 
-### Type
+### Usage
 
 ```ts
-function createResolver (basePath: string | URL): Resolver
+import { defineNuxtModule, createResolver } from '@nuxt/kit'
 
-interface Resolver {
-  resolve (...path: string[]): string
-  resolvePath (path: string, options?: ResolvePathOptions): Promise<string>
-}
+export default defineNuxtModule({
+  async setup (_, nuxt) {
+    const { resolve, resolvePath } = createResolver(import.meta.url)
+  },
+})
+```
 
-interface ResolvePathOptions {
-  cwd?: string
-  alias?: Record<string, string>
-  extensions?: string[]
-}
+### Type
+
+```ts
+function createResolver (basePath: string | URL): Resolver
 ```
 
 ### Parameters
 
-#### `basePath`
+**`basePath`**: A base path to resolve from. It can be a string or a URL.
 
-**Type**: `string`
+### Return Value
 
-**Required**: `true`
+The `createResolver` function returns an object with the following properties:
 
-Base path to resolve from.
+| Property      | Type                                                                         | Description                                                                                               |
+| ------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `resolve`     | `(path: string) => string`{lang="ts"}                                        | A function that resolves a path relative to the base path.                                                |
+| `resolvePath` | `(path: string, options?: ResolvePathOptions) => Promise<string>`{lang="ts"} | A function that resolves a path relative to the base path and respects Nuxt alias and extensions options. |
 
 ### Examples
 
 ```ts
-// https://github.com/vuejs/pinia/blob/v2/packages/nuxt
-import {
-  defineNuxtModule,
-  isNuxt2,
-  createResolver,
-} from '@nuxt/kit'
+import { createResolver, defineNuxtModule, isNuxt2 } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup(options, nuxt) {
+  setup (options, nuxt) {
     const resolver = createResolver(import.meta.url)
 
     nuxt.hook('modules:done', () => {
@@ -263,6 +209,6 @@ export default defineNuxtModule({
         addPlugin(resolver.resolve('./runtime/plugin.vue3'))
       }
     })
-  }
+  },
 })
 ```

package/3.api/5.kit/13.logging.md

@@ -14,6 +14,20 @@ Nuxt provides a logger instance that you can use to log messages with extra feat
 
 Returns a logger instance. It uses [consola](https://github.com/unjs/consola) under the hood.
 
+### Usage
+
+```ts twoslash
+import { defineNuxtModule, useLogger } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    const logger = useLogger('my-module')
+
+    logger.info('Hello from my module!')
+  },
+})
+```
+
 ### Type
 
 ```ts
@@ -22,44 +36,20 @@ function useLogger (tag?: string, options?: Partial<ConsolaOptions>): ConsolaIns
 
 ### Parameters
 
-#### `tag`
-
-**Type**: `string`
-
-**Optional**: `true`
-
-A tag to prefix all log messages with.
-
-#### `options`
+**`tag`**: A tag to suffix all log messages with.
 
-**Type**: `Partial<ConsolaOptions>`
-
-**Optional**: `true`
-
-Consola configuration options
+**`options`**: Consola configuration options.
 
 ### Examples
 
-```ts
-import { defineNuxtModule, useLogger } from '@nuxt/kit'
-
-export default defineNuxtModule({
-  setup(options, nuxt) {
-    const logger = useLogger('my-module')
-
-    logger.info('Hello from my module!')
-  }
-})
-```
-
-```ts
+```ts twoslash
 import { defineNuxtModule, useLogger } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup(options, nuxt) {
+  setup (options, nuxt) {
     const logger = useLogger('my-module', { level: options.quiet ? 0 : 3 })
 
     logger.info('Hello from my module!')
-  }
+  },
 })
 ```