Resolving - Nuxt — ContextQMD

Sometimes you need to resolve a path relative to the current module without knowing the name or extension. For example, you may want to add a plugin that is located in the same directory as the module. To handle these cases, Nuxt provides a set of utilities to resolve paths. resolvePath and resolveAlias are used to resolve paths relative to the current module. findPath is used to find the first existing file in a given set of paths. createResolver is used to create a resolver relative to the base path.

`resolvePath`

Resolves the full path to a file or directory, respecting Nuxt alias and extensions options. If a path could not be resolved, a normalized input path will be returned.

Usage

import { defineNuxtModule, resolvePath } from '@nuxt/kit'

export default defineNuxtModule({
  async setup () {
    const entrypoint = await resolvePath('@unhead/vue')
    console.log(`Unhead entrypoint is ${entrypoint}`)
  },
})

Type

function resolvePath (path: string, options?: ResolvePathOptions): Promise<string>

Parameters

path: A path to resolve.

options: Options to pass to the resolver. This object can have the following properties:

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

import { defineNuxtModule, resolvePath } from '@nuxt/kit'
import { join } from 'pathe'

const headlessComponents: ComponentGroup[] = [
  {
    relativePath: 'combobox/combobox.js',
    chunkName: 'headlessui/combobox',
    exports: [
      'Combobox',
      'ComboboxLabel',
      'ComboboxButton',
      'ComboboxInput',
      'ComboboxOptions',
      'ComboboxOption',
    ],
  },
]

export default defineNuxtModule({
  meta: {
    name: 'nuxt-headlessui',
    configKey: 'headlessui',
  },
  defaults: {
    prefix: 'Headless',
  },
  async setup (options) {
    const entrypoint = await resolvePath('@headlessui/vue')
    const root = join(entrypoint, '../components')

    for (const group of headlessComponents) {
      for (const e of group.exports) {
        addComponent(
          {
            name: e,
            export: e,
            filePath: join(root, group.relativePath),
            chunkName: group.chunkName,
            mode: 'all',
          },
        )
      }
    }
  },
})

`resolveAlias`

Resolves path aliases respecting Nuxt alias options.

Type

function resolveAlias (path: string, alias?: Record<string, string>): string

Parameters

path: A path to resolve.

alias: An object of aliases. If not provided, it will be read from nuxt.options.alias.

`findPath`

Try to resolve first existing file in a given set of paths.

Usage

import { defineNuxtModule, findPath } from '@nuxt/kit'
import { join } from 'pathe'

export default defineNuxtModule({
  async setup (_, nuxt) {
    // Resolve main (app.vue)
    const mainComponent = await findPath([
      join(nuxt.options.srcDir, 'App'),
      join(nuxt.options.srcDir, 'app'),
    ])
  },
})

Type

function findPath (paths: string | string[], options?: ResolvePathOptions, pathType: 'file' | 'dir'): Promise<string | null>

Parameters

paths: A path or an array of paths to resolve.

options: Options to pass to the resolver. This object can have the following properties:

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`

Creates resolver relative to base path.

::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/resolving-paths-and-injecting-assets-to-the-app?friend=nuxt" target="_blank"} Watch Vue School video about createResolver. ::

Usage

import { createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (_, nuxt) {
    const { resolve, resolvePath } = createResolver(import.meta.url)
  },
})

Type

function createResolver (basePath: string | URL): Resolver

Parameters

basePath: A base path to resolve from. It can be a string or a URL.

Return Value

The createResolver function returns an object with the following properties:

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

import { createResolver, defineNuxtModule, isNuxt2 } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    nuxt.hook('modules:done', () => {
      if (isNuxt2()) {
        addPlugin(resolver.resolve('./runtime/plugin.vue2'))
      } else {
        addPlugin(resolver.resolve('./runtime/plugin.vue3'))
      }
    })
  },
})