Checking Links on Build

The build scan runs after Nitro prerenders your pages. It inspects the links on every prerendered HTML page.

Only prerendered pages are scanned. If nuxt build prerenders no routes, the scan does not run, and the build logs Nuxt Link Checker scanned no pages. To scan your pages, use nuxt generate, or add routes to nitro.prerender.routes.

export default defineNuxtConfig({
  nitro: {
    prerender: {
      routes: ['/'],
      crawlLinks: true,
    },
  },
})

How Links Are Checked

The scan finds the status of each link as follows:

• A link to a prerendered page uses the status from prerendering. If the page is a redirect, the scan asks the built app for its status and Location.
• A link to a file in public/ passes without a request.
• A link to an external site passes without a request, unless you set fetchRemoteUrls: true.
• Any other internal link gets a HEAD request to your site.url, which is usually production.

The last case means a new page that is not prerendered and not deployed yet reports a 404. A page that exists only in production passes. Prerender such pages, or add them to excludeLinks.

If a server rejects HEAD, the scan retries with GET. An error reports the status the server sent. If the server answers with a redirect, the scan records the redirect for the redirects rule. Then it follows the redirect, and the other rules check the final page. If the scan cannot reach the server at all, it reports Could not reach the link with the cause, such as ENOTFOUND.

The summary counts links, not rule results. A link with two errors adds one to Total errors.

Throwing Build Errors

When building and deploying your app in a CI, you may like to disable the deployment if the scanner finds broken links.

To do so you can enable the failOnError option. This will exit the process with a non-zero exit code.

export default defineNuxtConfig({
  linkChecker: {
    failOnError: true,
  },
})

Check the Generate Reports guide for more details.

Disabling Build Scans

If you want to disable build link scanning, you can set runOnBuild to false in your nuxt.config:

export default defineNuxtConfig({
  linkChecker: {
    runOnBuild: false,
  },
})