or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-tldts

Library to work against complex domain names, subdomains and URIs

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/tldts@7.0.x

To install, run

npx @tessl/cli install tessl/npm-tldts@7.0.0

index.mddocs/

tldts - Blazing Fast URL Parsing

tldts is a JavaScript/TypeScript library to extract hostnames, domains, public suffixes, top-level domains and subdomains from URLs. It provides high-performance URL parsing (0.1 to 1 μs per input) with comprehensive Unicode/IDNA support, IPv4/IPv6 detection, and email parsing capabilities.

Package Information

  • Package Name: tldts
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install tldts

Core Imports

import { parse, getHostname, getDomain, getPublicSuffix, getSubdomain, getDomainWithoutSuffix } from "tldts";

For CommonJS:

const { parse, getHostname, getDomain } = require("tldts");

Type Imports: TypeScript types are not re-exported from the main package. If you need type definitions, import them from the core library:

import type { IResult, IOptions } from "tldts-core";

Basic Usage

import { parse, getDomain, getHostname } from "tldts";

// Parse a complete URL
const result = parse("https://www.example.co.uk/path");
console.log(result.domain); // "example.co.uk"
console.log(result.subdomain); // "www"
console.log(result.publicSuffix); // "co.uk"

// Extract specific components
const domain = getDomain("https://api.github.com/users");
console.log(domain); // "github.com"

const hostname = getHostname("https://secure.example.org:8080/admin");
console.log(hostname); // "secure.example.org"

Architecture

tldts is built around several key components:

  • Core Parser: High-performance parsing engine with early exit optimization
  • Public Suffix List: Continuously updated trie-based data structure for TLD recognition
  • Options System: Granular configuration for performance tuning and behavior customization
  • Type Safety: Full TypeScript integration with comprehensive interface definitions
  • Multi-format Support: Handles URLs, hostnames, email addresses, and IP addresses

Capabilities

Complete URL Parsing

Extracts all URL components in a single operation with comprehensive metadata.

/**
 * Parse URL or hostname and extract all components
 * @param url - URL or hostname string to parse
 * @param options - Optional parsing configuration
 * @returns Complete parsing result with all extracted components
 */
function parse(url: string, options?: Partial<IOptions>): IResult;

interface IResult {
  /** Extracted hostname from the input */
  hostname: string | null;
  /** Whether hostname is an IP address (IPv4 or IPv6) */
  isIp: boolean | null;
  /** Subdomain portion (everything before the domain) */
  subdomain: string | null;
  /** Full domain (domain + public suffix) */
  domain: string | null;
  /** Public suffix/TLD (e.g., "com", "co.uk") */
  publicSuffix: string | null;
  /** Domain without the public suffix (second-level domain) */
  domainWithoutSuffix: string | null;
  /** Whether public suffix comes from ICANN section */
  isIcann: boolean | null;
  /** Whether public suffix comes from Private section */
  isPrivate: boolean | null;
}

Hostname Extraction

Extracts hostname from URLs or validates hostname strings.

/**
 * Extract hostname from URL or hostname string
 * @param url - URL or hostname string
 * @param options - Optional parsing configuration
 * @returns Hostname string or null if invalid
 */
function getHostname(url: string, options?: Partial<IOptions>): string | null;

Usage Examples:

import { getHostname } from "tldts";

getHostname("https://www.example.com/path"); // "www.example.com"
getHostname("example.com"); // "example.com"
getHostname("https://user:pass@api.example.com:8080/v1"); // "api.example.com"
getHostname("mailto:user@example.org"); // "example.org"

Domain Extraction

Extracts the fully qualified domain (domain + public suffix).

/**
 * Extract fully qualified domain from URL or hostname
 * @param url - URL or hostname string
 * @param options - Optional parsing configuration
 * @returns Domain string or null if no valid domain found
 */
function getDomain(url: string, options?: Partial<IOptions>): string | null;

Usage Examples:

import { getDomain } from "tldts";

getDomain("https://www.google.com"); // "google.com"
getDomain("api.github.com"); // "github.com"
getDomain("secure.example.co.uk"); // "example.co.uk"
getDomain("localhost"); // null (unless validHosts specified)

Public Suffix Extraction

Extracts the public suffix (TLD) using the Mozilla Public Suffix List.

/**
 * Extract public suffix (TLD) from URL or hostname
 * @param url - URL or hostname string
 * @param options - Optional parsing configuration
 * @returns Public suffix string or null if none found
 */
function getPublicSuffix(url: string, options?: Partial<IOptions>): string | null;

Usage Examples:

import { getPublicSuffix } from "tldts";

getPublicSuffix("example.com"); // "com"
getPublicSuffix("example.co.uk"); // "co.uk"
getPublicSuffix("s3.amazonaws.com"); // "com"
getPublicSuffix("s3.amazonaws.com", { allowPrivateDomains: true }); // "s3.amazonaws.com"

Subdomain Extraction

Extracts the subdomain portion (everything before the domain).

/**
 * Extract subdomain from URL or hostname
 * @param url - URL or hostname string
 * @param options - Optional parsing configuration
 * @returns Subdomain string or null if none exists
 */
function getSubdomain(url: string, options?: Partial<IOptions>): string | null;

Usage Examples:

import { getSubdomain } from "tldts";

getSubdomain("www.example.com"); // "www"
getSubdomain("api.v2.example.com"); // "api.v2"
getSubdomain("example.com"); // ""
getSubdomain("secure.shop.example.co.uk"); // "secure.shop"

Domain Without Suffix Extraction

Extracts the domain without its public suffix (second-level domain).

/**
 * Extract domain without public suffix (second-level domain)
 * @param url - URL or hostname string
 * @param options - Optional parsing configuration
 * @returns Domain without suffix or null if no valid domain
 */
function getDomainWithoutSuffix(url: string, options?: Partial<IOptions>): string | null;

Usage Examples:

import { getDomainWithoutSuffix } from "tldts";

getDomainWithoutSuffix("example.com"); // "example"
getDomainWithoutSuffix("www.github.com"); // "github"
getDomainWithoutSuffix("secure.example.co.uk"); // "example"

Configuration Options

interface IOptions {
  /** Use suffixes from ICANN section (default: true) */
  allowIcannDomains: boolean;
  /** Use suffixes from Private section (default: false) */
  allowPrivateDomains: boolean;
  /** Perform IP address detection (default: true) */
  detectIp: boolean;
  /** Extract hostname from URLs (default: true) */
  extractHostname: boolean;
  /** Handle mixed URLs and hostnames (default: true) */
  mixedInputs: boolean;
  /** Additional valid hosts for localhost-style domains (default: null) */
  validHosts: string[] | null;
  /** Validate hostnames after extraction (default: true) */
  validateHostname: boolean;
}

Configuration Examples:

import { parse, getDomain } from "tldts";

// Enable private domains (like s3.amazonaws.com)
const result = parse("https://bucket.s3.amazonaws.com/file", {
  allowPrivateDomains: true
});
console.log(result.publicSuffix); // "s3.amazonaws.com"

// Handle localhost and custom domains
const domain = getDomain("api.localhost", {
  validHosts: ["localhost"]
});
console.log(domain); // "localhost"

// Performance optimization for hostname-only inputs
const hostname = parse("example.com", {
  extractHostname: false,
  mixedInputs: false
});

Special Input Handling

IPv4 and IPv6 Addresses

import { parse } from "tldts";

// IPv4 address
const ipv4Result = parse("https://192.168.1.1/admin");
console.log(ipv4Result.isIp); // true
console.log(ipv4Result.hostname); // "192.168.1.1"
console.log(ipv4Result.domain); // null

// IPv6 address
const ipv6Result = parse("https://[2001:db8::1]/api");
console.log(ipv6Result.isIp); // true
console.log(ipv6Result.hostname); // "2001:db8::1"

Email Addresses

import { parse } from "tldts";

const emailResult = parse("user@example.co.uk");
console.log(emailResult.hostname); // "example.co.uk"
console.log(emailResult.domain); // "example.co.uk"
console.log(emailResult.publicSuffix); // "co.uk"

Edge Cases and Error Handling

import { parse, getDomain } from "tldts";

// Invalid inputs return null values
console.log(getDomain("")); // null
console.log(getDomain("not-a-url")); // null

// Unknown TLDs are handled gracefully
const unknownTld = parse("example.unknown");
console.log(unknownTld.publicSuffix); // "unknown"
console.log(unknownTld.isIcann); // false

// Malformed URLs
const malformed = parse("ht!tp://bad-url");
console.log(malformed.hostname); // null

Command Line Interface

The package includes a CLI tool for parsing URLs from the command line:

# Parse single URL
npx tldts "https://www.example.co.uk/path"

# Parse from stdin
echo "https://api.github.com" | npx tldts

# Output format (JSON)
{
  "domain": "example.co.uk",
  "domainWithoutSuffix": "example",
  "hostname": "www.example.co.uk",
  "isIcann": true,
  "isIp": false,
  "isPrivate": false,
  "publicSuffix": "co.uk",
  "subdomain": "www"
}

Performance Characteristics

  • Speed: 0.1 to 1 microsecond per input
  • Memory: Optimized trie data structures with small footprint
  • Scalability: Handles millions of URLs per second
  • Bundle Size: Multiple optimized formats (UMD, ESM, CommonJS)
  • Early Exit: Internal optimization to avoid unnecessary computation

For maximum performance with known input types, use specialized options:

// For hostname-only inputs (fastest)
const options = {
  extractHostname: false,
  mixedInputs: false,
  validateHostname: false
};

// For domain extraction only (faster than full parse)
const domain = getDomain(input, options);