Autolinker.js

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported

  cause Attempting to `require()` Autolinker in a CommonJS environment while the package is treated as an ES Module, or vice versa, due to Node.js module resolution issues.
  fix For CommonJS, use `const Autolinker = require('autolinker');`. For ESM, use `import Autolinker from 'autolinker';`. Ensure your project's `package.json` `"type"` field and `tsconfig.json` `module` and `moduleResolution` options are correctly configured for your environment (e.g., `"type": "module"` for ESM, `"type": "commonjs"` for CJS).

• TypeError: Autolinker is not a constructor

  cause Trying to instantiate `Autolinker` as a class (`new Autolinker()`) but it was imported incorrectly, often due to using a named import `import { Autolinker } from 'autolinker';` instead of the default import.
  fix Change the import statement to `import Autolinker from 'autolinker';` for ESM/TypeScript environments. For CommonJS, ensure `const Autolinker = require('autolinker');` is used.

• Uncaught SyntaxError: Cannot use import statement outside a module

  cause Using `import Autolinker from 'autolinker';` in a non-ES module browser environment or a Node.js script not configured as an ES module.
  fix For browsers, include the `Autolinker.min.js` script directly via a `<script>` tag, which exposes `Autolinker` globally. For Node.js, ensure your `package.json` contains `"type": "module"` or use a `.mjs` file extension, or revert to CommonJS `require()` syntax.

Warnings

• breaking Autolinker v4.0.0 introduced significant breaking changes, primarily a complete rewrite of the URL parser from regular expressions to a finite state machine. This change, while greatly improving performance and preventing ReDoS attacks, removes the ability to override regular expressions in `Matcher` classes. The `urls.wwwMatches` config was also removed, and `Match.getType()` replaced `Match.type`.
  Fix: Review the official breaking changes documentation for v4.x.x, especially regarding URL parsing behavior and the `Match` object API. Adjust code that relied on custom regex or direct `Match.type` access.
• gotcha When migrating from older versions or other autolinking libraries, be aware that Autolinker.js explicitly handles HTML input to prevent common issues like double-nested anchor tags or clobbering existing `href` attributes. Directly manipulating innerHTML or using other string replacement methods alongside Autolinker may lead to unexpected results.
  Fix: Always pass raw or pre-processed text/HTML directly to `Autolinker.link()` and rely on its internal HTML parsing for correct behavior. Avoid manually replacing parts of the string that might contain valid HTML tags or already linked content.
• deprecated The codebase was converted to TypeScript and now uses ES6 exports. Direct overriding of regular expressions by assigning to `Matcher.prototype` is no longer supported since v2, which may affect highly customized implementations.
  Fix: Refactor custom linking logic to use the `replaceFn` option provided by `Autolinker` which offers a flexible way to modify generated links or even prevent linking for specific matches.
• gotcha Autolinker v3.16.2 reverted an attempted fix for Right-to-Left Override (RTLO) characters splitting links, meaning the library may not fully handle edge cases involving these characters and could result in improperly split links.
  Fix: No direct fix within the library currently for this specific issue. Users dealing with text containing RTLO characters should implement external sanitization or validation if this is a critical concern, or monitor for future patches.

Install

• npm install autolinker npm
• yarn add autolinker yarn
• pnpm add autolinker pnpm

Imports

• Autolinker
  wrong:

  import { Autolinker } from 'autolinker';

  correct:

  import Autolinker from 'autolinker';

  The primary `Autolinker` class is exported as a default export since v2. Using named import is incorrect.
• Autolinker (CommonJS)
  wrong:

  const autolinker = require('autolinker');

  correct:

  const Autolinker = require('autolinker');

  For CommonJS environments (Node.js), the package should be `require`d and typically aliased with a capital letter as it's a class.
• Match
  wrong:

  import { Match } from 'autolinker';

  correct:

  import Autolinker, { Match } from 'autolinker';

  The `Match` interface/type for TypeScript is available as a named export. Ensure you also import `Autolinker` as the default export if needed.

Quickstart

This quickstart demonstrates how to initialize Autolinker with various options and link a block of text, including a custom `replaceFn` to modify the generated anchor tags.

import Autolinker from 'autolinker';

const inputText: string = "Check out my website at example.com, email me at test@example.org, or call me at +1 (123) 456-7890. Also, find me on Twitter @myhandle and hashtag #myproject.";

const autolinker = new Autolinker({
  urls: { scheme: true, www: true, ipV4Matches: true },
  email: true,
  phone: true,
  mention: 'twitter',
  hashtag: 'twitter',
  newWindow: true,
  stripPrefix: false,
  // Custom replace function to add specific classes or attributes
  replaceFn: (match) => {
    const tag = match.buildTag();
    if (match.getType() === 'url') {
      tag.setAttr('class', 'my-url-link');
    }
    return tag;
  }
});

const linkedText: string = autolinker.link(inputText);

console.log(linkedText);
// Expected output: Check out my website at <a href="http://example.com" class="my-url-link" target="_blank" rel="noopener noreferrer">example.com</a>, email me at <a href="mailto:test@example.org" target="_blank" rel="noopener noreferrer">test@example.org</a>, or call me at <a href="tel:+11234567890" target="_blank" rel="noopener noreferrer">+1 (123) 456-7890</a>. Also, find me on Twitter <a href="https://twitter.com/myhandle" target="_blank" rel="noopener noreferrer">@myhandle</a> and hashtag <a href="https://twitter.com/hashtag/myproject" target="_blank" rel="noopener noreferrer">#myproject</a>.