Resolving

Source
Nuxt Kit provides utilities to resolve paths from the Nuxt root directory or a custom base.

Sometimes you need to resolve a path without knowing its name or extension. For example, you may want to add a plugin that is located in the same directory as a module. To handle these cases, Nuxt provides a set of utilities to resolve paths. resolvePath resolves paths from the Nuxt root directory by default, while resolveAlias applies configured aliases. findPath finds the first existing file in a given set of paths. createResolver creates a resolver relative to a 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:

PropertyTypeRequiredDescription
cwdstringfalseBase for resolving paths from. Default is Nuxt rootDir.
aliasRecord<string, string>falseAn object of aliases. Default is Nuxt configured aliases.
extensionsstring[]falseThe file extensions to try. Default is Nuxt configured extensions.
virtualbooleanfalseWhether to resolve files that exist in the Nuxt VFS (for example, as a Nuxt template).
fallbackToOriginalbooleanfalseWhether to fallback to the original path if the resolved path does not exist instead of returning the normalized input path.
resolvePath follows standard module resolution and does not search dependencies nested inside other packages. To resolve a dependency declared by your Nuxt module, use createResolver(import.meta.url).resolvePath(). This makes resolution independent of whether the package manager hoists the dependency.

Example

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:

PropertyTypeRequiredDescription
cwdstringfalseBase for resolving paths from. Default is Nuxt rootDir.
aliasRecord<string, string>falseAn object of aliases. Default is Nuxt configured aliases.
extensionsstring[]falseThe file extensions to try. Default is Nuxt configured extensions.
virtualbooleanfalseWhether to resolve files that exist in the Nuxt VFS (for example, as a Nuxt template).
fallbackToOriginalbooleanfalseWhether 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.

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:

PropertyTypeDescription
resolve(path: string) => stringA function that resolves a path relative to the base path.
resolvePath(path: string, options?: ResolvePathOptions) => Promise<string>A function that resolves a path relative to the base path and respects Nuxt alias and extensions options.

Example

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'))
      }
    })
  },
})