sfe-canonical-url

A pure, deterministic canonical-URL builder for headless and SSR apps, productized from SEO for Engineers, Volume 1, Chapter 19.

In a headless system the canonical URL must be computed in one place, deterministically, from a fixed set of inputs: a CMS override, the path, an optional locale, the request's search params, and the origin (read from the environment so preview deploys never emit production canonicals). This package is that one place. No browser, no network, no I/O — just a function.

Install

npm install sfe-canonical-url

Usage

import { computeCanonical } from 'sfe-canonical-url';

// SITE_ORIGIN=https://example.com in the environment
computeCanonical({ path: '/blog/some-post' });
// => 'https://example.com/blog/some-post'

// A valid CMS override always wins:
computeCanonical({ override: 'https://example.com/target', path: '/ignored' });
// => 'https://example.com/target'

// Only indexable params survive; the rest are dropped and order is normalized:
computeCanonical({
  path: '/search',
  params: new URLSearchParams('utm_source=x&page=2&sort=price'),
});
// => 'https://example.com/search?page=2'  (page is indexable; utm_source and sort are not)

API

• computeCanonical(input: CanonicalInputs): string
• isValidUrl(value: unknown): boolean
• DEFAULT_INDEXABLE_PARAMS: ReadonlySet<string>
• CanonicalInputs (type)

The origin is read from process.env.SITE_ORIGIN. Set it per environment so preview and staging deploys emit their own origin, never production's.

License

MIT © Nima Jafari