Nuxt Link Checker

nuxt-link-checker

Tested against the nuxt-link-checker release after 5.3.0 on Nuxt 4.5 (peer range Nuxt 3.9 to 5). The module inspects every <a href> in rendered HTML with 15 rules, at build time and in dev. It also ships two ESLint rules. Docs: https://nuxtseo.com/docs/link-checker

Setup

Config key: linkChecker. The module installs nuxt-site-config for you. @nuxtjs/seo already includes this module. Do not add it twice.

Set site.url to the production origin. The checker resolves internal links against it (see Traps). The trailing-slash rule reads site.trailingSlash, not a linkChecker option.

Automatic behaviour

• Build scan. After prerendering, the module inspects the links on each prerendered HTML page. It prints a tree per page, then a summary.
• Only prerendered pages are scanned. A plain nuxt build with no prerendered routes runs no inspections and logs Nuxt Link Checker scanned no pages. Use nuxt generate, or add routes to nitro.prerender.routes.
• The whole page is scanned, including <Teleport to="body"> links. An <a> without href gets a no-missing-href warning unless it has role="button".
• Default exclusions. excludeLinks starts with /^\/_/ and /^\/llms(-[\w-]+)?\.txt$/. Your entries are added to these; they do not replace them. With a non root app.baseURL, the base URL is also excluded.
• External links are not fetched. fetchRemoteUrls is false, so every absolute external link counts as a 200.
• Links to files in public/ pass without a request.
• Dev. With Nuxt DevTools on, the module adds a Link Checker DevTools tab and /__link-checker__/* server routes. On page squiggles need showLiveInspections: true.
• ESLint. With @nuxt/eslint, the module registers link-checker/valid-route (error) and link-checker/valid-sitemap-link (warn) for .vue, .ts, and .md files.

Fail CI on broken links

export default defineNuxtConfig({
  modules: ['nuxt-link-checker'],
  site: { url: 'https://example.com' },
  nitro: { prerender: { routes: ['/'], crawlLinks: true } },
  linkChecker: {
    failOnError: true,
    report: { json: true, markdown: true },
  },
})

Only errors fail the build. Errors come from no-error-response, missing-hash, and no-javascript. Every other rule is a warning. The count is the number of links with an error, not the number of errors.

With crawlLinks: true, Nitro crawls the broken link too and fails the build on its 404 before failOnError matters. To keep the build green and still get the report, set nitro.prerender.failOnError: false.

Reports

report.html, report.markdown, and report.json write link-checker-report.<ext> to .output/. When any report is on, the console shows only the summary. Read the report file for the link list.

• report.storage: a path relative to the root, or unstorage options.
• report.publish: true writes to .output/public/__link-checker__/. It adds X-Robots-Tag: noindex and a robots.txt disallow. The report is still public.

The JSON report is an array of { route, reports }. Each report has link, textContent, error[], warning[], and fix. fix is the suggested link, such as /about for a typo /abot.

Exclude links and pages

export default defineNuxtConfig({
  linkChecker: {
    excludeLinks: ['/admin/**', '/api/*', /\.(pdf|zip)$/],
    excludePages: ['/embed/**'],
    skipInspections: ['link-text', 'no-underscores'],
  },
})

• excludeLinks matches the link. excludePages matches the page that contains the link and skips all its links.
• String patterns are radix3 routes, not globs. * is one whole segment and ** is any depth. /_nuxt/file_*.pdf never matches. Use a RegExp for part of a segment.
• skipInspections takes rule ids. The ids are: absolute-site-urls, link-text, missing-hash, no-baseless, no-double-slashes, no-duplicate-query-params, no-error-response, no-javascript, no-missing-href, no-non-ascii-chars, no-underscores, no-uppercase-chars, no-whitespace, redirects, trailing-slash. An unknown id does nothing and gives no warning.