Novelty Promotes Magicians


    2.2.0 • Public • Published

    tld.js Build Status

    tld.js is a Node.js module written in JavaScript to work against complex domain names, subdomains and well-known TLDs.

    It answers with accuracy to questions like what is domain?, what is subdomain? and is TLD a well-known one?.

    tld.js runs fast, is fully tested and is safe to use in the browser (with browserify, webpack and others). Because it relies on Mozilla's public suffix list, now is a good time to say thank you Mozilla!


    # Regular install 
    npm install --save tldjs
    # You can update the list of well-known TLD during the install 
    npm install --save tldjs --tldjs-update-rules

    The latter is useful if you significantly rely on an up-to-date list of TLDs. You can list the recent changes (changes Atom Feed) to get a better idea of what is going on in the Public Suffix world.

    Using It

    const {parse, tldExists} = require('tldjs');
    // Checking only if TLD exists in URL or hostname
    // First TLD exists; the second does not.
    // Retrieving hostname related informations of a given URL

    👋 Try it your browser to see how it works.
    ⬇️ Read the documentation below to find out the available functions.


    This methods returns handy properties about a URL or a hostname.

    const tldjs = require('tldjs');
    // {
    //   "hostname": "",
    //   "isValid": true,
    //   "tldExists": true,
    //   "publicSuffix": "",
    //   "domain": "",
    //   "subdomain": ""
    // }
    // {
    //   "hostname": "domain.unknown",
    //   "isValid": true,
    //   "tldExists": false,
    //   "publicSuffix": "unknown",
    //   "domain": "domain.unknown",
    //   "subdomain": ""
    // }
    Property Name Type
    hostname String
    isValid Boolean Is the hostname valid according to the RFC?
    tldExists Boolean Is the TLD well-known or not?
    publicSuffix String
    domain String
    subdomain String

    Single purpose methods

    These methods are shorthands if you want to retrieve only a single value.


    Checks if the TLD is well-known for a given hostname — parseable with require('url').parse.

    const { tldExists } = tldjs;
    tldExists('');      // returns `true`
    tldExists('google.local');    // returns `false` (not an explicit registered TLD)
    tldExists('com');             // returns `true`
    tldExists('uk');              // returns `true`
    tldExists('');           // returns `true` (because `uk` is a valid TLD)
    tldExists(''); // returns `true` (still because `uk` is a valid TLD)
    tldExists('');    // returns `true` (still because `uk` is a valid TLD)
    tldExists(''); // returns `true`


    Returns the fully qualified domain from a given string — parseable with require('url').parse.

    const { getDomain } = tldjs;
    getDomain('');        // returns ``
    getDomain('');     // returns ``
    getDomain('');  // returns ``
    getDomain('');  // returns ``
    getDomain('');              // returns ``
    getDomain('');           // returns ``
    getDomain(''); // returns ``


    Returns the complete subdomain for a given string — parseable with require('url').parse.

    const { getSubdomain } = tldjs;
    getSubdomain('');             // returns ``
    getSubdomain('');          // returns `fr`
    getSubdomain('');           // returns ``
    getSubdomain('');       // returns `foo`
    getSubdomain('');  // returns ``
    getSubdomain('');                   // returns ``
    getSubdomain('');                // returns `fr`
    getSubdomain(''); // returns `secure`


    Returns the public suffix for a given string — parseable with require('url').parse.

    const { getPublicSuffix } = tldjs;
    getPublicSuffix('');       // returns `com`
    getPublicSuffix('');    // returns `com`
    getPublicSuffix('');     // returns ``
    getPublicSuffix(''); // returns ``
    getPublicSuffix('');   // returns `unknown`


    Checks the validity of a given string — parseable with require('url').parse. It does not check if the TLD is well-known.

    const { isValid } = tldjs;
    isValid('');      // returns `true`
    isValid('');     // returns `false`
    isValid('my.fake.domain');  // returns `true`
    isValid('localhost');       // returns `false`
    isValid(''); // returns `true`


    Retrieving subdomain of localhost and custom hostnames

    tld.js methods getDomain and getSubdomain are designed to work only with known and valid TLDs. This way, you can trust what a domain is.

    localhost is a valid hostname but not a TLD. Although you can instanciate your own flavour of tld.js with additional valid hosts:

    const tldjs = require('tldjs');
    tldjs.getDomain('localhost');           // returns null
    tldjs.getSubdomain('vhost.localhost');  // returns null
    const myTldjs = tldjs.fromUserSettings({
      validHosts: ['localhost']
    myTldjs.getDomain('localhost');           // returns 'localhost'
    myTldjs.getSubdomain('vhost.localhost');  // returns 'vhost'

    Updating the TLDs List

    Many libraries offer a list of TLDs. But, are they up-to-date? And how to update them?

    tld.js bundles a list of known TLDs but this list can become outdated. This is especially true if the package have not been updated on npm for a while.

    Hopefully for you, even if I'm flying over the world, if I've lost my Internet connection or even if you do manage your own list, you can update it by yourself, painlessly.

    How? By passing the --tldjs-update-rules to your npm install command:

    # anytime you reinstall your project 
    npm install --tldjs-update-rules
    # or if you add the dependency to your project 
    npm install --save tldjs --tldjs-update-rules

    Open an issue to request an update of the bundled TLDs.


    Provide a pull request (with tested code) to include your work in this main project. Issues may be awaiting for help so feel free to give a hand, with code or ideas.


    While interpreting the results, keep in mind that each "op" reported by the benchmark is processing 24 domains
    tldjs#isValid x 230,353 ops/sec ±10.99% (44 runs sampled)
    tldjs#extractHostname x 42,333 ops/sec ±2.82% (85 runs sampled)
    tldjs#tldExists x 15,083 ops/sec ±8.76% (54 runs sampled)
    tldjs#getPublicSuffix x 14,334 ops/sec ±8.00% (80 runs sampled)
    tldjs#getDomain x 15,092 ops/sec ±1.92% (84 runs sampled)
    tldjs#getSubdomain x 13,202 ops/sec ±3.66% (72 runs sampled)
    tldjs#parse x 8,561 ops/sec ±11.78% (55 runs sampled)

    You can measure the performance of tld.js on your hardware by running the following command:

    npx tldjs -c './bin/benchmark.js'


    MIT License.


    npm i tld2js

    DownloadsWeekly Downloads






    Last publish


    • zan