Nuxt Link Checker v6.0.0

Introduction

Nuxt Link Checker v6 supports Nuxt 4.6 and Nuxt 5. It ships in Nuxt SEO v6.

This release removes Nuxt 3 and Nuxt Content v2 support. Failure messages now show the real HTTP status. The checker no longer passes when it skips links.

Check the breaking changes before you upgrade. For a guided migration, use the LLM upgrade prompt.

Some features shipped in 5.x minor releases. These include the comark-content provider (#104) and a faster prerender scan (#103). This page lists only the changes after v5.3.0.

Real Failure Statuses

In v5, every failed link check except a timeout read Should not respond with status code 404 (Not Found).. A 500, a 410, a DNS error and a refused connection all looked the same.

v6 reports the status that the server sent. If a server rejects HEAD with 405 or 501, the checker retries with GET. If no response arrives, the message names the network error code. (#109)

Should not respond with status code 404 (Page not found: /foo).
Could not reach the link (ECONNREFUSED).

No Silent Passes

Several paths let the checker pass while it skipped links. v6 closes them. (#110)

The build scan inspects <a> elements with no href. The no-missing-href rule now fires at build.
The build scan reads the whole document. It now includes links that <Teleport to="body"> renders.
Page titles feed the "Did you mean" suggestions.
A nuxt build with no prerendered pages logs Nuxt Link Checker scanned no pages.
The Markdown report shows the pages checked and the pages with issues.
The ESLint rules warn once when .nuxt/link-checker/routes.json is missing.
valid-sitemap-link stays quiet until the sitemap URLs reach routes.json.

Nested Route Discovery

Route discovery now walks nested pages and keeps absolute child paths. The ESLint valid-route rule and the DevTools suggestions use the real leaf paths. (#120)

Typed Runtime Entries

Import app functions from #link-checker/app. Import server functions from #link-checker/server. (#114)

app/utils/links.ts

import { createFilter, inspect, isNonFetchableLink } from '#link-checker/app'

server/utils/links.ts

import { getLinkResponse, inspect } from '#link-checker/server'

Agent Skill

The package ships an Agent Skill at skills/nuxt-link-checker/SKILL.md. Coding agents read it from node_modules. It covers the build scan scope, the config, and the traps that make the checker pass or fail by mistake. (#107)

You can also get the Skill on skilld.dev/gh/harlan-zw/nuxt-link-checker.

Breaking Changes

Nuxt 4.6 and Node 22.22.3

v6 requires Nuxt ^4.6.0 || ^5.0.0. v5 accepted Nuxt ^3.9.0 || ^4.0.0 || ^5.0.0. (#114)

v6 also requires Node ^22.22.3 || ^24.15.0 || >=26.0.0.

package.json

{
  "devDependencies": {
    "nuxt": "^4.6.0"
  }
}

Nuxt Content v2 Removed

The Nuxt Content integration requires @nuxt/content 3.6.0 or later. v5 accepted Nuxt Content v2. (#114)

v6 deletes the content-v2 provider and the compatibility shim for Content versions before 3.6.

package.json

-"@nuxt/content": "^2.13.0"
+"@nuxt/content": "^3.6.0"

If you use Nuxt Content v2, migrate to Content v3 first. Read the Nuxt Content v3 migration guide.

Site Config v5

Nuxt Link Checker requires nuxt-site-config 5.0.0 or later. v5 accepted version 3.2 or later. (#114, #128)

The module now loads Site Config as a native Nuxt module dependency. If your package.json pins nuxt-site-config, upgrade it.

package.json

-"nuxt-site-config": "^3.2.0"
+"nuxt-site-config": "^5.0.0"

Check the Site Config v5 release notes for its own changes.

Sitemap v9 and `nuxt-simple-sitemap`

The Sitemap integration requires @nuxtjs/sitemap 9.0.0 or later. v5 accepted version 7 or later. (#114)

v6 no longer detects the legacy nuxt-simple-sitemap package.

nuxt.config.ts

// Before
export default defineNuxtConfig({
  modules: ['nuxt-simple-sitemap', 'nuxt-link-checker'],
})

// After
export default defineNuxtConfig({
  modules: ['@nuxtjs/sitemap', 'nuxt-link-checker'],
})

Failure Message Text

The no-error-response message now carries the real status and status text. An unreachable link reports status 0. (#109)

// Before: every failure except a timeout
Should not respond with status code 404 (Not Found).

// After: the server's status
Should not respond with status code 500 (Internal Server Error).

// After: no response
Could not reach the link (ENOTFOUND).

If a script parses the reports for 404 (Not Found), update it. Also handle other statuses and status 0.

Removed v1 Options Now Warn

v6 logs a warning for the v1 options failOn404, exclude, siteUrl and trailingSlash. The warning names the replacement. These options did nothing in v5 either. (#110)

nuxt.config.ts

// Before
export default defineNuxtConfig({
  linkChecker: {
    failOn404: true,
    exclude: ['/admin/**'],
    siteUrl: 'https://example.com',
  },
})

// After
export default defineNuxtConfig({
  site: { url: 'https://example.com' },
  linkChecker: {
    failOnError: true,
    excludeLinks: ['/admin/**'],
  },
})

DevTools Host Package

The Link Checker DevTools tab now loads through nuxtseo-devtools-host. Without it, the tab shows an install button. (#114)

pnpm add -D nuxtseo-devtools-host

LLM Upgrade Prompt

Paste this into Claude, ChatGPT, or any LLM to migrate your codebase.

# Upgrade Guide: nuxt-link-checker v5 to v6.0.0

You are helping me upgrade nuxt-link-checker from v5 to v6.0.0 in my Nuxt project.

## Breaking Changes

### 1. Nuxt and Node Versions

**What changed:** v6 requires Nuxt `^4.6.0 || ^5.0.0` and Node `^22.22.3 || ^24.15.0 || >=26.0.0`.

**Search my codebase for:** `"nuxt":` in package.json, `engines`, `.nvmrc`, `.node-version`, CI Node versions.

**Action:** Upgrade Nuxt to 4.6 or later. Use a supported Node version.

### 2. Nuxt Content v2 Removed

**What changed:** The content integration requires `@nuxt/content` 3.6.0 or later.

**Search my codebase for:** `"@nuxt/content":`

**Regex pattern:** `"@nuxt/content":\s*"[\^~]?2\.`

**Before:**
```json
{ "dependencies": { "@nuxt/content": "^2.13.0" } }
```

**After:**
```json
{ "dependencies": { "@nuxt/content": "^3.6.0" } }
```

If the project uses Content v2 APIs (`queryContent`, `<ContentDoc>`{lang="html"}, `documentDriven`), stop and tell me. Content v3 needs its own migration first.

### 3. Site Config v5

**What changed:** nuxt-link-checker requires `nuxt-site-config` 5.0.0 or later.

**Search my codebase for:** `"nuxt-site-config":`

**Regex pattern:** `"nuxt-site-config":\s*"[\^~]?[34]\.`

**Action:** If package.json pins `nuxt-site-config`, change it to `^5.0.0`.

### 4. Sitemap v9 and nuxt-simple-sitemap

**What changed:** The sitemap integration requires `@nuxtjs/sitemap` 9.0.0 or later. The module no longer detects `nuxt-simple-sitemap`.

**Search my codebase for:** `nuxt-simple-sitemap`, `"@nuxtjs/sitemap":`

**Regex pattern:** `nuxt-simple-sitemap|"@nuxtjs/sitemap":\s*"[\^~]?[78]\.`

**Before:**
```ts
export default defineNuxtConfig({
  modules: ['nuxt-simple-sitemap', 'nuxt-link-checker'],
})
```

**After:**
```ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/sitemap', 'nuxt-link-checker'],
})
```

### 5. Failure Message Text

**What changed:** `no-error-response` messages carry the real status. Unreachable links report status `0` and `Could not reach the link (<code>)`.

**Search my codebase for:** `Not Found`, `link-checker-report.json`, `debug-link-responses.json`

**Regex pattern:** `404 \(Not Found\)|link-checker-report\.json`

**Action:** Update scripts that parse report text for `404 (Not Found)`. Handle any status code and status `0`.

### 6. Removed v1 Options

**What changed:** v6 warns about the v1 options `failOn404`, `exclude`, `siteUrl` and `trailingSlash`.

**Search my codebase for:** `failOn404`, `siteUrl`, `trailingSlash` and `exclude:` inside `linkChecker`.

**Regex pattern:** `failOn404|siteUrl|trailingSlash|\bexclude:`

**Before:**
```ts
linkChecker: { failOn404: true, exclude: ['/admin/**'], siteUrl: 'https://example.com', trailingSlash: true }
```

**After:**
```ts
site: { url: 'https://example.com', trailingSlash: true },
linkChecker: { failOnError: true, excludeLinks: ['/admin/**'] },
```

### 7. DevTools Host Package

**What changed:** The DevTools tab needs `nuxtseo-devtools-host` as a dev dependency.

**Action:** If the project uses Nuxt DevTools, run `pnpm add -D nuxtseo-devtools-host`.

## Verification Checklist

1. `pnpm install` (update lockfile)
2. `npx nuxt typecheck` (catch type errors)
3. `pnpm generate` or `pnpm build` with prerendered routes (run the build scan)
4. Read the Link Checker summary for new findings from teleported links and `<a>`{lang="html"} without `href`
5. `pnpm test` (catch runtime regressions)

---

Please scan my codebase for all affected patterns listed above and generate a complete migration plan. For each file that needs changes, show me the exact diff.

Upgrading

If you use @nuxtjs/seo, upgrade it to v6 instead. It includes Nuxt Link Checker v6.

Otherwise, upgrade nuxt-link-checker directly:

# pnpm
pnpm add nuxt-link-checker@^6

# npm
npm install nuxt-link-checker@^6

# yarn
yarn add nuxt-link-checker@^6

Changelog

Compare changes

Enhancements

Prepare Link Checker 6 for Nuxt 4.6 (#114)
Ship an Agent Skill in the package (#107)

Fixes

Report the real status when a link check fails (#109)
Stop passing silently when the checker skips links (#110)
Discover nested and absolute page routes (#120)
Align Skill metadata with the Agent Skills spec (#127)
Flag 303, 307 and 308 redirects, not only 301 and 302 (#132)

Refactors

Use native Site Config module dependencies (#128)

Documentation

Describe what the build scan checks and its defaults (#108)
Add the module icon and unify the README badges (#115)

Chore

CI, test fixture, and maintenance updates (#112, #113, #116, #117, #124, #125, #126)

Contributors

Harlan Wilton

Was this page helpful?

Edit page Report an issue

Nuxt SEO v6

Install Nuxt Link Checker

Configuration

Nuxt Link Checker v6.0.0

Introduction

Real Failure Statuses

No Silent Passes

Nested Route Discovery

Typed Runtime Entries

Agent Skill

Breaking Changes

Nuxt 4.6 and Node 22.22.3

Nuxt Content v2 Removed

Site Config v5

Sitemap v9 and nuxt-simple-sitemap

Failure Message Text

Removed v1 Options Now Warn

DevTools Host Package

LLM Upgrade Prompt

Upgrading

Changelog

Enhancements

Fixes

Refactors

Documentation

Chore

Contributors

Related

Sitemap v9 and `nuxt-simple-sitemap`