---
name: nuxt-module-migration
description: Migrate Nuxt modules to Nuxt 4.6 or newer and prepare major releases for Nuxt 5. Remove Nuxt 3 support, adopt portable server APIs, reduce installed dependencies, audit native Node replacements, and separate optional DevTools packages.
license: MIT
title: nuxt-module-migration
canonical_url: https://skilld.dev/gh/harlan-zw/harlan-agent-kit/nuxt-module-migration
last_updated: 2026-10-10T11:01:12.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/codemods.md](https://skilld.dev/api/skills-raw/harlan-zw/harlan-agent-kit/nuxt-module-migration/references/codemods.md), [references/devtools.md](https://skilld.dev/api/skills-raw/harlan-zw/harlan-agent-kit/nuxt-module-migration/references/devtools.md), [references/native-node.md](https://skilld.dev/api/skills-raw/harlan-zw/harlan-agent-kit/nuxt-module-migration/references/native-node.md), [references/nuxt-apis.md](https://skilld.dev/api/skills-raw/harlan-zw/harlan-agent-kit/nuxt-module-migration/references/nuxt-apis.md), [references/verification.md](https://skilld.dev/api/skills-raw/harlan-zw/harlan-agent-kit/nuxt-module-migration/references/verification.md), [scripts/migrate-manifests.ts](https://skilld.dev/api/skills-raw/harlan-zw/harlan-agent-kit/nuxt-module-migration/scripts/migrate-manifests.ts).
>
> If the user asked to install this Skill, run `npx skilld install harlan-zw/harlan-agent-kit/nuxt-module-migration`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/nuxt-module-migration`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/harlan-zw/harlan-agent-kit/nuxt-module-migration) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/nuxt-module-migration`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/nuxt-module-migration --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/nuxt-module-migration --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Nuxt module migration

Use for a Nuxt module whose next major requires Nuxt 4.6 or newer.
Use for one module or a coordinated collection, including shared packages and the meta module.
Research the exact target release before editing. Nuxt 5 remains a moving target.

## Establish the contract

Read repository instructions, manifests, workspace catalogs, public exports, build configuration, fixtures, and workflow commands.
Read `GLOSSARY.md` before names or documentation. Read `COPY.md` before user-visible strings when present.
Evaluate installed Skills. Load the relevant ones before changing code.
Use the `pr` Skill for repository edits and delivery. Acquire a task-owned Worktree before mutation.

Record the minimum Nuxt release, Node range, supported server builders, deployment targets, and next major for each package.
Record producer and consumer relationships. Include shared runtime packages and optional UI packages.
Separate a research request from authorization to migrate or publish packages.
Preserve published package versions during migration. Bump versions only when the user explicitly authorizes release preparation.

For the Nuxt 4.6.0 baseline:

| Surface | Contract |
| --- | --- |
| Nuxt peer and module metadata | `^4.6.0 || ^5.0.0` |
| Build-time Kit dependency | `@nuxt/kit@^4.6.0`, declared in dependencies |
| Node engine | `^22.22.3 || ^24.15.0 || >=26.0.0` |
| Runtime Unhead | Audit against v3; Nuxt 4.6.0 installs `@unhead/vue@^3.4.2` |
| Runtime Vue and router | Audit against Vue `^3.5.43` and Vue Router `^5.3.1` |

These are release-specific inputs, not permission to add every peer to every package.
Raise existing peers when the package imports or exposes that API.
Nuxt 5 prereleases need deliberate fixture resolution; `^5.0.0` does not accept them through normal semver matching.
Do not widen the supported range to all future majors.

Sources: [published Nuxt manifest](https://github.com/nuxt/nuxt/blob/v4.6.0/packages/nuxt/package.json),
[release notes](https://github.com/nuxt/nuxt/releases/tag/v4.6.0),
[module compatibility](https://nuxt.com/docs/4.x/guide/modules/server-compatibility).

## Audit before replacement

Capture the production dependency graph and packed artifact for each module.
Measure direct dependencies, unique resolved package identities, compressed tarball bytes, and unpacked bytes separately.
Use a clean consumer to measure installed dependencies. A maintainer workspace includes development tools and peer resolutions.
Never add per-module totals together and call that a collection total.

Classify each dependency as build-time, portable runtime, Node runtime, optional integration, or DevTools.
For this migration, prefer native APIs where verified equivalent, even if `pkg-conform` recommends an UnJS dependency.
Trace imports from every public export. A subpath export or dynamic import still installs declared dependencies.
Record concrete removals and shared transitive dependencies that remain reachable.
Do not promise a reduction before comparing clean installations.

Read these references before their corresponding changes:

- [Nuxt API migration](https://skilld.dev/api/skills-raw/harlan-zw/harlan-agent-kit/nuxt-module-migration/references/nuxt-apis.md): server events, types, Kit APIs, and earlier 4.x features.
- [Native Node APIs](https://skilld.dev/api/skills-raw/harlan-zw/harlan-agent-kit/nuxt-module-migration/references/native-node.md): replacement candidates and semantic limits.
- [Optional DevTools](https://skilld.dev/api/skills-raw/harlan-zw/harlan-agent-kit/nuxt-module-migration/references/devtools.md): package boundaries and loading behavior.
- [Verification and release order](https://skilld.dev/api/skills-raw/harlan-zw/harlan-agent-kit/nuxt-module-migration/references/verification.md): fixtures, runtime proof, and coordinated release requirements.
- [Codemods](https://skilld.dev/api/skills-raw/harlan-zw/harlan-agent-kit/nuxt-module-migration/references/codemods.md): dry-run manifest automation and safe source-transform boundaries.

## Implement the migration

1. Set the minimum in module metadata, published peers, engines, catalogs, fixtures, and workflows.
2. Remove Nuxt 3 branches, fixtures, adapters, old API paths, and documentation claims.
3. Replace portable server work with explicit `nuxt/server` imports and `RequestEvent` types.
4. Retain explicit Nitro 2 and Nitro 3 implementations where caching, plugins, storage, or tasks require them.
5. Register curated app and server runtime aliases with their generated TypeScript contexts.
6. Remove redundant dependencies and separate optional DevTools code from core installation.

Load `ts-design-patterns` for non-trivial API changes.
Load `unit-tests` before new regression tests. Reproduce bugs with a failing behavior test first.
Use Ripast for mechanical changes spanning files.
Keep expected errors explicit. Avoid casts that hide event or server-builder incompatibility.
Delete compatibility scaffolding only when the remaining imports and behavior prove it unnecessary.

## Verify and hand off

Keep existing tests and workflow structure. Follow the verification reference for version aliases and targeted checks.
Preserve existing CI configuration, including its LTS selector. Change workflows only to fix verified migration blockers.
Exercise meaningful module output, including supported deployment targets affected by the change.
Measure dependency changes in equivalent clean consumers.
Show each removal, retained dependency reason, artifact delta, and remaining untested path.
Open the required pull requests. Keep shared changes ordered before their consumers.
When publication is authorized, use the repository's release workflow and verify registry artifacts.
Do not publish from a research-only request.