Registry / http-networking / psl
library2025.5.26jsnpmunverified

psl is a JavaScript library designed for parsing domain names based on the widely adopted Public Suffix List (PSL). This list is a community-maintained resource, primarily initiated by the Mozilla Project, which identifies "public suffixes"—domain parts under which users can directly register names (e.g., .com, .co.uk, .pvt.k12.wy.us). The library's current stable version is 1.15.0. It receives regular updates to its internal Public Suffix List rules, ensuring accuracy with the latest additions and changes, with the most recent update occurring in v1.15.0 (December 2024). Key differentiators include its adherence to the official PSL, testing against Mozilla's own test data, and significant performance enhancements introduced in v1.14.0 (over 100x improvement for parsing). It provides robust support for both Node.js and browser environments, offering ESM, CommonJS, and UMD distributions, and includes TypeScript type definitions since v1.11.0, making it suitable for modern JavaScript and TypeScript projects.

npm install psl
INSTALL
IMPORT
SIG · PSL
P
psl
http-networkingjavascriptv2025.5.26
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

psl
import psl from 'psl';
const psl = require('psl');
Correct for ESM environments since v1.13.0. For CommonJS, use `require`.
psl (CommonJS)
const psl = require('psl');
import psl from 'psl';
Correct for CommonJS environments. Was the primary import method before v1.11.0 and fully supported again since v1.13.0 for backward compatibility.
ParsedDomain
import type { ParsedDomain } from 'psl';
Interface for the object returned by `psl.parse()`. Types are available since v1.11.0. The primary `psl` export is a default export.

Demonstrates how to parse various domain name structures, extract components (TLD, SLD, subdomain), and retrieve the base domain using `psl.parse()` and `psl.get()`, including handling null inputs.

import psl from 'psl'; // Parse a simple domain const simpleDomain = 'example.com'; const parsedSimple = psl.parse(simpleDomain); console.log(`Parsing "${simpleDomain}":`); console.log(` TLD: ${parsedSimple.tld}`); // 'com' console.log(` SLD: ${parsedSimple.sld}`); // 'example' console.log(` Domain: ${parsedSimple.domain}`); // 'example.com' console.log(` Subdomain: ${parsedSimple.subdomain}`); // null // Parse a domain with multiple subdomains const complexDomain = 'a.b.c.foo.co.uk'; const parsedComplex = psl.parse(complexDomain); console.log(`\nParsing "${complexDomain}":`); console.log(` TLD: ${parsedComplex.tld}`); // 'co.uk' console.log(` SLD: ${parsedComplex.sld}`); // 'foo' console.log(` Domain: ${parsedComplex.domain}`); // 'foo.co.uk' console.log(` Subdomain: ${parsedComplex.subdomain}`); // 'a.b.c' // Get just the domain name (SLD + TLD) const domainOnly = psl.get('www.sub.example.net'); console.log(`\nGetting domain for "www.sub.example.net": ${domainOnly}`); // 'example.net' // Handle invalid or null input for psl.get const invalidDomain = psl.get('invalid'); const nullDomain = psl.get(null); console.log(`Getting domain for "invalid": ${invalidDomain}`); // null console.log(`Getting domain for null: ${nullDomain}`); // null
Debug
Known issues
breakingESM support (via `"type": "module"`) was introduced in v1.11.0, but quickly rolled back in v1.12.0 due to compatibility issues with older Node.js versions and certain bundlers. Full ESM support, alongside continued CommonJS compatibility, was re-introduced and stabilized in v1.13.0. Users upgrading from v1.10.0 or earlier to v1.11.0 may have experienced broken imports, which were fixed by reverting to v1.12.0 or upgrading to v1.13.0+.
fix
Ensure you are using `psl@^1.13.0` for consistent ESM and CommonJS support. Check your `package.json` and lock files.
affects: 1.11.0
gotchaParsing performance for `psl.parse()` and `psl.get()` was significantly improved by over 100x in v1.14.0 by switching the internal rule storage from an Array to a Map. While not a breaking change, applications relying on `psl` in performance-critical loops with versions older than v1.14.0 might experience noticeable slowdowns compared to the latest releases.
fix
Upgrade to `psl@^1.14.0` or newer to benefit from the substantial performance enhancements.
affects: <1.14.0
gotchaThe Public Suffix List rules are regularly updated. While `psl` itself updates its bundled list with new releases, applications that rely on the very latest PSL rules for domain validation or parsing might find that `psl` releases lag slightly behind the absolute newest public suffix additions. Ensure your `psl` dependency is kept up-to-date to benefit from the latest list.
fix
Regularly update `psl` to the latest minor or patch versions (e.g., `npm update psl` or `yarn upgrade psl`) to incorporate the most recent Public Suffix List rules.
affects: *
Errors
Common errors & fixes
ReferenceError: require is not defined
Attempting to use `require('psl')` in a JavaScript module (`.mjs` file or `package.json` with `"type": "module"`) environment.
fix
Change `const psl = require('psl');` to `import psl from 'psl';`. Ensure your project's `package.json` or file extension correctly signals ESM if you intend to use `import`.
SyntaxError: Cannot use import statement outside a module
Attempting to use `import psl from 'psl';` in a CommonJS (`.js` file without `"type": "module"` in `package.json`) environment.
fix
Change `import psl from 'psl';` to `const psl = require('psl');`. If you intend to use ESM, configure your project as a module (e.g., add `"type": "module"` to `package.json` or use `.mjs` file extension).
TypeError: Cannot read properties of null (reading 'tld')
Attempting to access properties (like `tld`, `sld`, `domain`, `subdomain`) of the object returned by `psl.parse(domain)` when `domain` was `null`, `undefined`, or an invalid format that `psl` could not parse into a valid structure, causing `psl.parse` to return `null`.
fix
Always check if the result of `psl.parse(domain)` is `null` before attempting to access its properties. For example: `const parsed = psl.parse(domain); if (parsed) { console.log(parsed.tld); } else { console.log('Invalid domain or null input'); }`.
Upgrade
Version history
2025.5.26latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
15 hits · last 30 days
node
14
Resources
psl — npm install psl · libregistry