gil-wiki/reference/4.api/5.kit/3.compatibility.md

title, description, links

title	description	links
Compatibility	Nuxt Kit provides a set of utilities to help you check the compatibility of your modules with different Nuxt versions.	label icon to size Source i-simple-icons-github https://github.com/nuxt/nuxt/blob/main/packages/kit/src/compatibility.ts 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.

Usage

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

export default defineNuxtModule({
  async setup (_options, nuxt) {
    const issues = await checkNuxtCompatibility({ nuxt: '^2.16.0' }, nuxt)
    if (issues.length) {
      console.warn('Nuxt compatibility issues found:\n' + issues.toString())
    } else {
      // do something
    }
  },
})

Type

function checkNuxtCompatibility (constraints: NuxtCompatibility, nuxt?: Nuxt): Promise<NuxtCompatibilityIssues>

Parameters

constraints: Version and builder constraints to check against. It accepts the following properties:

Property	Type	Required	Description
nuxt	string	false	Nuxt version in semver format. Versions may be defined in Node.js way, for example: >=2.15.0 <3.0.0.
bridge	Record<string, string | false>{lang="ts"}	false	Specifies version constraints or disables compatibility for specific Nuxt builders like vite, webpack, or rspack. Use false to disable.

nuxt: 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

// @errors: 2391
import type { Nuxt, NuxtCompatibility } from '@nuxt/schema'
// ---cut---
function assertNuxtCompatibility (constraints: NuxtCompatibility, nuxt?: Nuxt): Promise<true>

Parameters

constraints: Version and builder constraints to check against. Refer to the constraints table in checkNuxtCompatibility for details.

nuxt: 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.

Usage

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

export default defineNuxtModule({
  async setup (_options, nuxt) {
    const usingNewPostcss = await hasNuxtCompatibility({ nuxt: '^2.16.0' }, nuxt)
    if (usingNewPostcss) {
      // do something
    } else {
      // do something else
    }
  },
})

Type

function hasNuxtCompatibility (constraints: NuxtCompatibility, nuxt?: Nuxt): Promise<boolean>

Parameters

constraints: Version and builder constraints to check against. Refer to the constraints table in checkNuxtCompatibility for details.

nuxt: Nuxt instance. If not provided, it will be retrieved from the context via useNuxt() call.

isNuxtMajorVersion

Check if current Nuxt instance is of specified major version

Usage

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

export default defineNuxtModule({
  setup () {
    if (isNuxtMajorVersion(3)) {
      // do something for Nuxt 3
    } else {
      // do something else for other versions
    }
  },
})

Type

function isNuxtMajorVersion (major: number, nuxt?: Nuxt): boolean

Parameters

major: Major version to check against.

nuxt: 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.

::note Use isNuxtMajorVersion(2, nuxt) instead. This may be removed in @nuxt/kit v5 or a future major version. ::

Type

function isNuxt3 (nuxt?: Nuxt): boolean

Parameters

nuxt: 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.

::note Use isNuxtMajorVersion(2, nuxt) instead. This may be removed in @nuxt/kit v5 or a future major version. ::

Type

function isNuxt2 (nuxt?: Nuxt): boolean

Parameters

nuxt: Nuxt instance. If not provided, it will be retrieved from the context via useNuxt() call.

getNuxtVersion

Returns the current Nuxt version.

Type

function getNuxtVersion (nuxt?: Nuxt): string

Parameters

nuxt: Nuxt instance. If not provided, it will be retrieved from the context via useNuxt() call.