tldts 7.x

Complete instructions

Verified against tldts@7.4.12 on 2026-09-08. 2 of 2 examples executed.

tldts

Use the v7 function-oriented API. Import named functions from tldts:

import assert from 'node:assert/strict';
import {
  parse,
  getHostname,
  getDomain,
  getFullDomain,
  getPublicSuffix,
  getSubdomain,
  getDomainWithoutSuffix,
} from 'tldts';

const parsed = parse('http://www.writethedocs.org/conf/eu/2017/');
assert.equal(parsed.domain, 'writethedocs.org');
assert.equal(parsed.domainWithoutSuffix, 'writethedocs');
assert.equal(parsed.hostname, 'www.writethedocs.org');
assert.equal(parsed.isIcann, true);
assert.equal(parsed.isIp, false);
assert.equal(parsed.isPrivate, false);
assert.equal(parsed.publicSuffix, 'org');
assert.equal(parsed.subdomain, 'www');

assert.equal(
  getHostname('https://user:password@example.co.uk:8080/some/path?and&query#hash'),
  'example.co.uk',
);
assert.equal(getDomain('foo.google.co.uk'), 'google.co.uk');
assert.equal(getFullDomain('foo.google.co.uk'), 'foo.google.co.uk');
assert.equal(getPublicSuffix('google.co.uk'), 'co.uk');
assert.equal(getSubdomain('moar.foo.google.co.uk'), 'moar.foo');
assert.equal(getDomainWithoutSuffix('foo.google.co.uk'), 'google');
assert.equal(getFullDomain('1.2.3.4'), null);

parse(url, options?) returns parsed hostname information including hostname, domain, domainWithoutSuffix, publicSuffix, subdomain, isIcann, isPrivate, and isIp. The helper functions accept the same URL-or-host-like string and optional options. String-returning helpers return string | null.

Use getFullDomain when you want the complete non-IP domain. It returns null for an IP address. The older/common API shape remains function-based: code using parse, getHostname, getDomain, getPublicSuffix, getSubdomain, and getDomainWithoutSuffix is still the right general shape. v7 also documents getFullDomain.

Private suffixes

ICANN domains are enabled by default, while private suffixes are not. Pass allowPrivateDomains: true when private suffixes should participate:

import assert from 'node:assert/strict';
import { parse, getPublicSuffix, getDomain } from 'tldts';

const defaultResult = parse('spark-public.s3.amazonaws.com');
assert.equal(defaultResult.domain, 'amazonaws.com');
assert.equal(defaultResult.isPrivate, false);

const privateResult = parse('spark-public.s3.amazonaws.com', {
  allowPrivateDomains: true,
});
assert.equal(privateResult.domain, 'spark-public.s3.amazonaws.com');
assert.equal(privateResult.domainWithoutSuffix, 'spark-public');
assert.equal(privateResult.hostname, 'spark-public.s3.amazonaws.com');
assert.equal(privateResult.isIcann, false);
assert.equal(privateResult.isIp, false);
assert.equal(privateResult.isPrivate, true);
assert.equal(privateResult.publicSuffix, 's3.amazonaws.com');
assert.equal(privateResult.subdomain, '');

assert.equal(
  getPublicSuffix('s3.amazonaws.com', { allowPrivateDomains: true }),
  's3.amazonaws.com',
);
assert.equal(
  getDomain('spark-public.s3.amazonaws.com', { allowPrivateDomains: true }),
  'spark-public.s3.amazonaws.com',
);

Do not assume PSL-style private-suffix results are implicit. Without allowPrivateDomains: true, the private suffix is ignored; with it, s3.amazonaws.com is treated as the public suffix in the example above.

Options and the v7 validation change

The documented options are:

• allowIcannDomains — defaults to true.
• allowPrivateDomains — defaults to false.
• extractHostname — defaults to true.
• validateHostname — defaults to true.
• detectIp
• mixedInputs
• validHosts
• detectSpecialUse

In v7, hostname validation is consistent between getHostname and parse(url).hostname. With validation enabled, an invalid hostname stops processing and produces null as described by the v7 change. Set validateHostname: false to restore permissive parsing and allow processing to continue for inputs the validator would reject:

const result = parse(input, { validateHostname: false });

Do not carry forward pre-v7 assumptions that getHostname and parse(...).hostname can differ for invalid hostnames.

CLI boundary

The package also has a CLI, but it is not a plain function call. Invoke it through the package runner or an installed executable, for example:

npx tldts 'http://www.writethedocs.org/conf/eu/2017/'
echo 'https://example.com' | npx tldts

Programmatic parsing does not require the CLI, a build step, or a package-owned runner.

Does not cover

This skill does not cover the detailed semantics of every documented option (allowIcannDomains, extractHostname, detectIp, mixedInputs, validHosts, or detectSpecialUse), the complete hostname-validation rule set, the full CLI option set, or the package's suffix database beyond the examples shown. The research does not establish additional return-shape edge cases for malformed inputs, localhost, or other special-use names.