nuxt
nuxt/test-utils & happy-dom incompatibility (vitest ^4.x.x)
Description
@nuxt/[email protected] has outdated peer dependency constraints that prevent users from upgrading to the latest stable versions of vitest (v4.x) and happy-dom (v19.x/v20.x).
This creates a dependency management challenge and blocks projects from using the latest features and bug fixes in these dependencies.
Current Peer Dependencies (v3.19.2)
{
"vitest": "^3.2.0",
"happy-dom": "^9.10.9 || ^10.0.0 || ^11.0.0 || ^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0"
}
Latest Stable Versions (as of October 2025)
- vitest: 4.0.2 (stable)
- @vitest/coverage-v8: 4.0.2
- happy-dom: 20.0.8
Impact
When attempting to upgrade dependencies to their latest versions, users encounter peer dependency conflicts:
Error Example
npm error ERESOLVE could not resolve
npm error
npm error While resolving: @nuxt/[email protected]
npm error Found: [email protected]
npm error node_modules/happy-dom
npm error dev happy-dom@"^20.0.8" from the root project
npm error
npm error Could not resolve dependency:
npm error peerOptional happy-dom@"^9.10.9 || ^10.0.0 || ... || ^18.0.0" from @nuxt/[email protected]
npm error
npm error Conflicting peer dependency: [email protected]
Reproduction
Minimal Reproduction Repository
You can reproduce this issue with the following steps:
1. Create a new Nuxt project with test-utils
npx nuxi@latest init nuxt-test-utils-issue
cd nuxt-test-utils-issue
2. Install @nuxt/test-utils and testing dependencies
npm install --save-dev @nuxt/test-utils vitest @vitest/coverage-v8 happy-dom @vue/test-utils
3. Attempt to upgrade to latest stable versions
npm install --save-dev vitest@^4.0.2 @vitest/coverage-v8@^4.0.2 happy-dom@^20.0.8
Result: Installation succeeds with --legacy-peer-deps but shows peer dependency warnings.
4. Try to install with npm ci (simulating CI/CD)
rm -rf node_modules
npm ci
Result: Fails with ERESOLVE error.
Alternative: Reproduce with existing project
If you have an existing Nuxt project:
Install current stable versions
npm install --save-dev @nuxt/test-utils@^3.19.2
Try to upgrade test dependencies
npm install --save-dev vitest@latest @vitest/coverage-v8@latest happy-dom@latest
This will fail with peer dependency conflicts
npm ci
Expected package.json after upgrade attempt
{
"devDependencies": {
"@nuxt/test-utils": "^3.19.2",
"@vitest/coverage-v8": "^4.0.2",
"@vue/test-utils": "^2.4.6",
"happy-dom": "^20.0.8",
"nuxt": "^4.1.3",
"vitest": "^4.0.2"
}
}
Error Output
npm error code ERESOLVE
npm error ERESOLVE could not resolve
npm error
npm error While resolving: @nuxt/[email protected]
npm error Found: [email protected]
npm error node_modules/happy-dom
npm error dev happy-dom@"^20.0.8" from the root project
npm error peerOptional happy-dom@"*" from [email protected]
npm error node_modules/vitest
npm error dev vitest@"^4.0.2" from the root project
npm error peer vitest@"4.0.2" from @vitest/[email protected]
npm error node_modules/@vitest/coverage-v8
npm error dev @vitest/coverage-v8@"^4.0.2" from the root project
npm error
npm error Could not resolve dependency:
npm error peerOptional happy-dom@"^9.10.9 || ^10.0.0 || ^11.0.0 || ^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0" from @nuxt/[email protected]
npm error node_modules/@nuxt/test-utils
npm error dev @nuxt/test-utils@"^3.19.2" from the root project
npm error @nuxt/test-utils@">=3.13.1" from [email protected]
npm error node_modules/vitest-environment-nuxt
npm error vitest-environment-nuxt@"^1.0.1" from @nuxt/[email protected]
npm error
npm error Conflicting peer dependency: [email protected]
npm error node_modules/happy-dom
npm error peerOptional happy-dom@"^9.10.9 || ^10.0.0 || ^11.0.0 || ^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0" from @nuxt/[email protected]
npm error node_modules/@nuxt/test-utils
npm error dev @nuxt/test-utils@"^3.19.2" from the root project
npm error @nuxt/test-utils@">=3.13.1" from [email protected]
npm error node_modules/vitest-environment-nuxt
npm error vitest-environment-nuxt@"^1.0.1" from @nuxt/[email protected]
npm error
npm error Fix the upstream dependency conflict, or retry
npm error this command with --force or --legacy-peer-deps
CI/CD Reproduction
Create .gitlab-ci.yml or .github/workflows/test.yml:
.gitlab-ci.yml
test:
image: node:24
script:
- npm ci
- npm run test
Result: Pipeline fails at npm ci step with the above error. Verification that issue is in @nuxt/test-utils You can verify the peer dependency constraint by running:
npm view @nuxt/[email protected] peerDependencies
Output:
{
"happy-dom": "^9.10.9 || ^10.0.0 || ^11.0.0 || ^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0",
"vitest": "^3.2.0"
}
Compare with latest vitest peer dependencies:
npm view [email protected] peerDependencies
Output:
{
"happy-dom": "*"
}
This shows that [email protected] supports any version of happy-dom, but @nuxt/[email protected] limits it to v18.x maximum.
This reproduction section provides:
- Step-by-step instructions to reproduce the issue
- Multiple reproduction methods (new project, existing project, CI/CD)
- Expected vs actual behavior
- Complete error output
- Verification commands showing the root cause
Additional context
Update the peer dependency ranges in package.json to include:
- vitest@^3.2.0 || ^4.0.0
- happy-dom versions up to ^20.0.0
This would allow users to stay on the latest stable versions while maintaining backward compatibility with v3.x users.
This will also enable to fix the critical issue with happy-dom <= ^20.0.0. https://github.com/advisories/GHSA-37j7-fg3j-429f
@ExEr7um the update for happy-dom is fixed but the upgrade of vitest to version 4 is not yet "fixed" as vitest is explicitly required in version 3.2.4.
