Compatibility
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 { defineNuxtModule, checkNuxtCompatibility } 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> | 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
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({
async 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.
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.
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.
Programmatic Usage
Nuxt Kit provides a set of utilities to help you work with Nuxt programmatically. These functions allow you to load Nuxt, build Nuxt, and load Nuxt configuration.
Auto-imports
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.