Site Linkcheck

Site Linkcheck is a configurable Playwright link checker. It crawls internal pages, validates internal and external links, and writes JSON/CSV reports.

Install

Use the published npm package:

npm install -g site-linkcheck
linkcheck --version

Or run it without installing globally:

npx site-linkcheck --version

For local development from source:

nvm use
npm install
npx playwright install chromium

Quick Start

npm run config:validate
npm run check

Run any website directly:

npx tsx src/run.ts crawl https://example.com --max-depth 1 --max-links 100 --reports-dir reports

Run from configuration:

npx tsx src/run.ts crawl --config linkcheck.config.json --target example

CLI

linkcheck crawl <url>
linkcheck crawl --config linkcheck.config.json --target example
linkcheck config validate --config linkcheck.config.json
linkcheck reports merge reports
linkcheck notify --provider slack --report reports/_merged-file.json
linkcheck notify --provider telegram --report reports/_merged-file.json

Useful crawl options:

• --entrypoint <path> repeatable entrypoint override.
• --max-depth <number> crawl depth.
• --max-requests <number> max pages per crawl.
• --max-links <number> max checked links per crawl (0 in config means unlimited).
• --concurrency <number> parallel browser work.
• --timeout <ms> navigation timeout.
• --exclude <pattern> paths to check but not crawl recursively.
• --ignore-extension <ext> URL extensions to skip.
• --storage-state <path> Playwright storageState file.
• --header <name:value> custom HTTP header.
• --skip-from-reports incremental mode.
• --fail-on-broken exit with code 2 when broken links are found.
• --json machine-readable command output.

Configuration

The default config lives in linkcheck.config.json and is described by schemas/linkcheck.schema.json.

{
  "$schema": "./schemas/linkcheck.schema.json",
  "targets": {
    "example": {
      "baseUrl": "https://example.com",
      "entrypoints": ["/"],
      "crawl": {
        "maxDepth": 1,
        "maxRequestsPerCrawl": 50,
        "maxLinksToCheckPerCrawl": 0,
        "concurrency": 2
      }
    }
  },
  "reports": {
    "directory": "./reports",
    "formats": ["json", "csv"]
  },
  "notifications": []
}

Authentication is optional. For authenticated checks, generate a Playwright storage state yourself and reference it:

{
  "targets": {
    "private-docs": {
      "baseUrl": "https://docs.example.com",
      "auth": {
        "storageState": "./secrets/docs.storage.json",
        "headers": {
          "x-linkcheck-run": "ci"
        }
      }
    }
  }
}

Do not store secrets in config. Use environment variables or CI secrets.

Notifications

Slack is optional:

export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."
npx tsx src/run.ts notify --provider slack --report reports/_merged-file.json

Telegram is optional:

export TELEGRAM_BOT_TOKEN="..."
export TELEGRAM_CHAT_ID="..."
npx tsx src/run.ts notify --provider telegram --report reports/_merged-file.json

CI

This repository includes both .github/workflows/ci.yml and .gitlab-ci.yml. Both run the same project commands:

npm ci
npx playwright install chromium
npm run typecheck
npm test
npm run test:coverage
npm run config:validate

Scheduled crawl jobs should call npm run check or a target-specific linkcheck crawl --config ... --target ... command.

Exit Codes

• 0: command completed.
• 1: runtime error.
• 2: broken links were found with --fail-on-broken.
• 3: invalid arguments or configuration.
• 4: required notification failed.

Development

nvm use
npm run typecheck
npm test
npm run test:coverage