Nuxt•4w ago

module bump to nuxt 4

As a module author when to bump the module's dependency to nuxt 4? What if I want to support both Nuxt 3 and 4 apps?

8 Replies

Hi @rrd. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave: ---------------------- As a Nuxt module author, you should consider bumping your module's Nuxt dependency to v4 when you want to take advantage of new features, APIs, or breaking changes introduced in Nuxt 4 that are not compatible with Nuxt 3. However, if you want your module to support both Nuxt 3 and Nuxt 4 applications, you can specify compatibility constraints in your module's meta configuration using the compatibility property. This allows your module to declare which Nuxt versions it supports, and users will receive a warning if they try to use it with an unsupported version. Here’s how you can specify compatibility for both Nuxt 3 and 4:

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'your-module',
    configKey: 'yourModule',
    compatibility: {
      nuxt: '>=3.0.0 <5.0.0'
    }
  },
  // ... other module options
})

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'your-module',
    configKey: 'yourModule',
    compatibility: {
      nuxt: '>=3.0.0 <5.0.0'
    }
  },
  // ... other module options
})

This example ensures your module is compatible with any Nuxt version from 3.x up to (but not including) 5.x. If you use APIs or features that are only available in Nuxt 4, you should update the compatibility range accordingly and consider releasing a major version of your module for Nuxt 4 only. If you need to check compatibility programmatically (for example, to enable/disable features based on the Nuxt version), you can use utilities like checkNuxtCompatibility, assertNuxtCompatibility, or hasNuxtCompatibility from @nuxt/kit in your module setup function Nuxt Kit Compatibility Utilities. Best practice:
- Do not advertise your module as "for Nuxt 3" or "for Nuxt 4" specifically; instead, use "for Nuxt" and set version constraints in meta.compatibility to avoid ecosystem fragmentation Module Best Practices. - If you need to drop Nuxt 3 support due to breaking changes, bump your module’s major version and update the compatibility range to ^4.0.0. In summary:
- Bump your module’s Nuxt dependency to v4 when you require Nuxt 4–specific features or APIs. - To support both Nuxt 3 and 4, set the appropriate compatibility range in your module’s meta and avoid using breaking changes that would prevent Nuxt 3 support Module Compatibility. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•4w ago

<@826042540469780502> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

rrdOP•4w ago

@kapa.ai so the module's nuxt version and the app's nuxt version can be different

kapa.ai•4w ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- Yes, the Nuxt version specified in your module's compatibility constraints (in the module's meta.compatibility.nuxt field) can be different from the Nuxt version used in the consuming app. The purpose of the compatibility field is to declare which Nuxt versions your module supports. When a user installs your module, Nuxt will check these constraints and warn (or disable the module) if the app's Nuxt version does not satisfy the module's requirements. For example, if your module declares:

meta: {
  compatibility: {
    nuxt: '>=3.0.0 <5.0.0'
  }
}

meta: {
  compatibility: {
    nuxt: '>=3.0.0 <5.0.0'
  }
}

This means your module is compatible with any Nuxt version from 3.x up to (but not including) 5.x. If the app is using Nuxt 4, the module will work. If the app is using Nuxt 2, the module will be disabled due to incompatibility, and a warning will be shown Defining Module Compatibility Requirements. So, the module's declared compatible Nuxt versions and the actual Nuxt version used in the app can differ, but the module will only be enabled if the app's Nuxt version matches the declared compatibility range. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•4w ago

<@826042540469780502> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

rrdOP•4w ago

@kapa.ai what about the module's nuxt/kit peer dependency

kapa.ai•4w ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- The knowledge sources do not explicitly mention strict requirements or best practices for setting the @nuxt/kit peer dependency version in your module's package.json. However, they do provide some relevant guidance: - Nuxt Kit (@nuxt/kit) is the recommended utility for module authors and is published as a separate package from Nuxt itself. It is used to define modules and interact with Nuxt internals Nuxt Kit Guide, Monorepo Guide. - It is recommended to use the latest version of @nuxt/kit that is equal to or greater than the Nuxt version you intend to support, to avoid unexpected behavior. If you install it separately, ensure the versions of @nuxt/kit and @nuxt/schema are equal to or greater than your Nuxt version Nuxt Kit Usage. - You do not need to add @nuxt/kit to your project's dependencies when developing local modules inside a Nuxt app, as Nuxt provides it automatically. But for published modules, you should declare it as a peer dependency to ensure compatibility Local Modules. In summary:
- For published modules, declare @nuxt/kit as a peer dependency in your package.json. - Set the version range to match the Nuxt versions you support (e.g., ^3.0.0 || ^4.0.0 if you support both Nuxt 3 and 4). - Always ensure your module uses a compatible or newer version of @nuxt/kit relative to the Nuxt version. If you need more specific guidance on version ranges, the knowledge sources do not provide an explicit recommendation. If in doubt, align your @nuxt/kit peer dependency with the Nuxt versions you declare in your module's compatibility field. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•4w ago

<@826042540469780502> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

Gaming

Programming

module bump to nuxt 4

Did you find this page helpful?