next-broken-links

About

This is a CLI tool that will check broken links in your Next.js project.

The experimental nextjs Statically Typed Links feature is not enough for catch all segments. This tool helps in that case.

Plus as we check links directly in the .next (or out) directory, we also check for broken links coming from CMS or other external sources. Whereas the next features is only limited to the <Link> tags present directly in the code.
But that's also a limit of our tool as we can only check server side rendered links.

Features

• Check broken links for public assets (images, json etc...)
• Check broken links for sitemap.xml
• Check broken links for all <a> tags (including <Link>)
• Check broken links for all <img> tags

Installation

bun install @vahor/next-broken-links -D

Usage

After a nextjs build, run the following command:

bunx @vahor/next-broken-links

or

bun next-broken-links

It will output the following:

✔ Extracted links from all pages
✔ Found 0 broken links

If you have broken links, it will output the following:

✔ Extracted links from all pages
✖ Found 5 broken links

index.html (4 broken links)
        - /hello/world/again
        - /incorrect.json
        - https://vahor.fr/invalid.json
        - https://vahor.fr/this/also/fails

sitemap.xml (1 broken links)
        - https://vahor.fr/this/should/fail

Options

• --config <path> - Path to your next.config.js file.
  • If not set, it will try to find a next.config.js (mjs, cjs, ts or js) file in the current directory.
• --domain <domain> - Domain to check links against.
  • If not set, non relative links will be ignored.
• --verbose - Enable verbose mode.
• --output <type> - Output type: 'export' for static export, undefined for standard build.
  • Only used when --no-config is specified.
• --distDir <path> - Custom dist directory path.
  • Only used when --no-config is specified.
• --no-config - Skip parsing next.config file and use provided options.
  • Useful to avoid installing dependencies present in next.config.js (e.g., contentlayer).
• --ignore <pattern> - Ignore links matching the given pattern.
  • Can be used multiple times. Example: --ignore "**/*.zip" --ignore "**/*.json" to ignore links ending with .zip or .json.

Example

# For static export without parsing config
bunx @vahor/next-broken-links --no-config --output export

# For standard build with custom dist directory
bunx @vahor/next-broken-links --no-config --distDir custom-dist

# For static export with custom dist directory
bunx @vahor/next-broken-links --no-config --output export --distDir custom-out

Who is using this?

• vahor.fr (source)