linkify-it

linkify-it is a links-recognition library built for accuracy over convenience shortcuts: it uses a purpose-built regex construction system to correctly handle full Unicode text, including astral characters and internationalized domains, rather than relying on a single “good enough” URL regex. It ships default recognizers for http(s):, ftp:, mailto:, and protocol-relative // links, plus optional fuzzy matching for bare domains, IPs, and emails when strict schema prefixes aren’t required.

Its small API surface (test, match, matchAtStart) and chainable configuration methods (.add(), .set(), .tlds()) make it straightforward to extend, most notably as the link-detection engine used inside markdown-it for autolinking bare URLs in Markdown source. A dedicated pathological-input test suite guards its hand-built regexes against catastrophic backtracking, a common failure mode for URL-matching libraries.

What You Get

• A single LinkifyIt class you can instantiate with zero config and start scanning text immediately.
• Full Unicode-aware URL and email detection, including international domains and astral characters.
• Chainable configuration API (.tlds(), .add(), .set()) for extending or restricting recognized schemas and TLDs.
• TypeScript types and TSDoc-driven API reference published via typedoc.
• A dual ESM/CommonJS build ready to import in either module system.

Common Use Cases

• Autolinking URLs and emails in user-generated text before rendering.
• Powering Markdown autolink detection inside parsers like markdown-it.
• Recognizing custom app-specific URI schemes via pluggable validators.
• Pre-filtering text for the presence of links before running heavier processing.

Under The Hood

Architecture A LinkifyIt class orchestrates schema-based matching (http/https/ftp/mailto/relative-protocol) by delegating pattern construction to a separate REBuilder class, which lazily builds and caches Unicode-aware regexes for each rule (schema search, fuzzy link, fuzzy email, mailto validator, and more). The core match() method runs a single linear scan that merges three candidate cursors — schema-prefixed matches, fuzzy-link candidates, and fuzzy-email candidates — choosing the lowest-index, longest match at each step to produce non-overlapping results. This separation between regex construction (REBuilder) and scanning state (LinkifyIt) means swapping the rebuilder or overriding normalize() customizes behavior without touching the scanning loop.

Tech Stack Written in TypeScript and compiled to a dual ESM/CJS build (build/index.mjs, build/index.cjs.js) with bundled .d.ts types generated via Rollup and rollup-plugin-dts. The only runtime dependency is uc.micro, a small package of Unicode character-category regex sources (Any, Cc, Z, P) used to build correctly-scoped character classes. Documentation is generated with typedoc and published as a static API reference; a small demo site is built with Vite and vite-plugin-singlefile.

Code Quality Tests run on Node’s native test runner (node:test) with node:assert, driven largely by a large data file of link/expected-URL pairs (test/fixtures/links.txt) alongside a dedicated api.test.mjs, a build.test.mjs that verifies the compiled dist output, and a pathological.test.mjs specifically targeting catastrophic-backtracking regressions in the hand-built regexes. The public API is fully typed with TSDoc comments, linted via ESLint’s neostandard config, and type-checked with tsc —noEmit as part of the standard test script, with c8 producing coverage reports.

API Design The public surface is intentionally small and ergonomic: a single LinkifyIt class exposes test/match/matchAtStart, and every configuration method (.tlds(), .add(), .set()) returns this for chaining. Sensible defaults (fuzzy email matching on, a capped maxLength) mean useful behavior requires zero configuration — new LinkifyIt().test(text) works out of the box — while every public method carries a TSDoc @example that also feeds the published typedoc reference site. The dual ESM/CJS exports map means the package works without bundler configuration in either module system.