tld.js

By default, getDomain and getSubdomain only work with known and valid TLDs. Because localhost is not a registered TLD, these methods will return null for it.

To support custom hostnames or localhost, use tldjs.fromUserSettings() to create a new instance with validHosts defined.

const tldjs = require('tldjs');

// Default behavior
tldjs.getDomain('localhost'); // null

// Custom behavior
const myTldjs = tldjs.fromUserSettings({
  validHosts: ['localhost']
});

myTldjs.getDomain('localhost'); // 'localhost'
myTldjs.getSubdomain('vhost.localhost'); // 'vhost'

You can install tldjs via npm. If you require the most up-to-date list of well-known TLDs (Public Suffix List), use the --tldjs-update-rules flag during installation.

# Regular install
npm install --save tldjs

# Install with updated TLD rules
npm install --save tldjs --tldjs-update-rules

If you only need a specific piece of information, use these shorthand methods. Most accept strings parseable by Node's require('url').parse.

const { 
  tldExists, 
  getDomain, 
  getSubdomain, 
  getPublicSuffix, 
  isValidHostname 
} = require('tldjs');

The tldjs.parse() method returns an object containing various properties about a given URL or hostname. This is the most comprehensive way to inspect a domain string.

const tldjs = require('tldjs');

tldjs.parse('https://spark-public.s3.amazonaws.com/dataanalysis/loansData.csv');
// Returns:
// {
//   hostname: 'spark-public.s3.amazonaws.com',
//   isValid: true,
//   isIp: false,
//   tldExists: true,
//   publicSuffix: 's3.amazonaws.com',
//   domain: 'spark-public.s3.amazonaws.com',
//   subdomain: ''
// }

The object returned by tldjs.parse() contains the following properties:

| Property Name | Type | Description |
| --- | --- | --- |
| `hostname` | `String` | The extracted hostname |
| `isValid` | `Boolean` | Is the hostname valid according to the RFC? |
| `tldExists` | `Boolean` | Is the TLD well-known or not? |
| `publicSuffix`| `String` | The public suffix |
| `domain` | `String` | The fully qualified domain |
| `subdomain` | `String` | The subdomain |

If you only need one specific part of a URL, tldjs provides convenience wrappers that call parse() with the appropriate early-stop step. These are more efficient than calling parse() and manually accessing a property.

• tldExists(url): Returns boolean. Checks if the TLD exists.
• getPublicSuffix(url): Returns string. Extracts the public suffix.
• getDomain(url): Returns string | null. Extracts the domain.
• getSubdomain(url): Returns string. Extracts the subdomain.
• isValidHostname(url): Returns boolean. Checks if the hostname is valid.
• extractHostname(url): Returns string. Extracts the hostname from a URL.

const tldjs = require('tldjs');

const domain = tldjs.getDomain('https://sub.example.com');
const suffix = tldjs.getPublicSuffix('example.co.uk');
const exists = tldjs.tldExists('not-a-real-tld');

You can create a custom instance of tldjs with specific rules or behaviors using fromUserSettings(options). This is useful if you want to provide your own TLD rules, a custom list of valid hosts, or a custom hostname extraction logic.

FactoryOptions object:

• rules: The suffix trie rules (from suffix-trie.js).
• validHosts: An array of strings representing valid hosts.
• extractHostname: A function (string) => string | null used to pull the hostname from a URL.

const tldjs = require('tldjs');

const customTldjs = tldjs.fromUserSettings({
  validHosts: ['example.com'],
  extractHostname: (url) => { /* custom logic */ }
});

const result = customTldjs.parse('https://example.com');

The ParseResult object is the standard output for the parse() method. It contains the following fields:

The getPublicSuffix() method returns the public suffix for a given string.

const { getPublicSuffix } = require('tldjs');

getPublicSuffix('google.co.uk');     // 'co.uk'
getPublicSuffix('s3.amazonaws.com'); // 's3.amazonaws.com'

The getSubdomain() method returns the complete subdomain for a given string.

const { getSubdomain } = require('tldjs');

getSubdomain('fr.google.com');          // 'fr'
getSubdomain('moar.foo.google.co.uk'); // 'moar.foo'

The tldExists() method checks if the TLD in a given hostname is part of the well-known public suffix list.

const { tldExists } = require('tldjs');

tldExists('google.com');      // true
tldExists('google.local');    // false
tldExists('co.uk');           // true