linkproofer
v0.1.2
Published
LinkProofer is a CLI application for proofing links in your project.
Downloads
17
Maintainers
Readme
LinkProofer is a CLI application for proofing links in your project.
Store your links in js
or ts
files, and verify the links with the LinkProofer CLI script.
✨ Features
- Out-of-the-box Typescript support.
- Customizable entry (Provide your own filepath glob, or store links in *.linkproof.<js | ts> files).
- Support for absolute or relative links.
- Run LinkProofer checks locally, or in CI.
- Lightweight! (~50 kB).
Why use LinkProofer?
There are lots of link checkers out there, and many will scrape your site's html. HTML scraping solutions can fall short when...
- Your site uses SSR, instead of pre-generating all pages
- Your site's pages are behind authentication
- The links on the page are lazy-loaded
- You want to scrape the site before a PR is merged.
Instead of scraping your site, LinkProofer will have you store your links in configured js
or ts
files, and check those links via the CLI, or through CI.
📦 Installation
yarn install --dev linkproofer
or
npm install --save-dev linkproofer
🔧 Setting up your project
Create a global.linkproof.ts
or global.linkproof.js
at the root of your project, with the following code:
const linkproof = {
MY_PORTFOLIO_URL: "https://johalloran.dev",
};
export default linkproof;
Note ⚠️. The link object needs to be the default export for LinkProofer to work.
You can even use this URL in one of your pages if you want, to get an idea how LinkProofer is used:
// ...
<h1>
Linking to <a href={links.MY_PORTFOLIO_URL}>My Portfolio!</a>
</h1>
Now at the root of your project, run:
npm run linkproofer
or
yarn linkproofer
You should see an audit of all your links (just MY_PORTFOLIO_URL
in our case).
You can create any *.linkproof.<js | ts>
file in your project, and the containing links will be validated anytime LinkProofer is run.
⚙️ Linkproofing our custom files
By default, LinkProofer will look in any \*_/_.linkproof.<js | ts>
file in your project. You can customize this by passing a custom --files
flag into the CLI
npm run linkproofer --files **/*/mylinksfile.ts
🤖 Automating Checks
Linkproofer can be run in a GitHub action to validate all links are properly working.
Add the following action: .github/workflows/linkproof.yml
name: Check Links
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
linkproofer:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [16.x]
steps:
- uses: actions/checkout@v3
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
- name: yarn install
run: |
yarn install
env:
CI: true
- name: linkproofer
run: |
yarn linkproofer
env:
CI: true
📁 Using relative paths
If you have deployment previews setup with a service like Netlify or Vercel, you can configure the LinkProofer baseURL
to look for relative links in your deployment preview
Your GitHub action step will look something like:
- name: linkproofer
run: |
yarn linkproofer --baseURL https://portfolio-avatar-git-${{ github.head_ref }}-jamespohalloran.vercel.app
env:
CI: true
In the above example, https://portfolio-avatar-git
and -jamespohalloran.vercel.app
will need to be replaced with your Vercel/Netlify project's specific info.
You can use one of the following packages to wait for your deployment to finish, before checking relative links:
- https://github.com/marketplace/actions/wait-for-netlify
- https://github.com/marketplace/actions/await-for-vercel-deployment
📖 CLI Usage
Usage: linkproofer [options]
Options:
-V, --version output the version number
-f, --files <files> Filepath pattern for files in which linkproofer should check for links
-v, --verbose Log out all checked links (not just the failures)
-o, --outputDir <outputDir> Directory to put the compiled output files. (Default dist). This directory should be added to your .gitignore
-b, --baseURL <baseURL> baseURL to use for relative links.
-h, --help display help for command