dnscontrol/documentation/functions/global/require.md

name	parameters	ts_ignore
require	path	true

require(...) loads the specified JavaScript or JSON file, allowing to split your configuration across multiple files.

A better name for this function might be "include".

If the supplied path string ends with .js, the file is interpreted as JavaScript code, almost as though its contents had been included in the currently-executing file. If the path string ends with .json, require() returns the JSON.parse() of the file's contents.

If the path string begins with a ./, it is interpreted relative to the currently-loading file (which may not be the file where the require() statement is, if called within a function). Otherwise it is interpreted relative to the program's working directory at the time of the call.

Example 1: Simple

In this example, we separate our macros in one file, and put groups of domains in 3 other files. The result is a cleaner separation of code vs. domains.

{% code title="dnsconfig.js" %}

require("lib/macros.json");

require("domains/main.json");
require("domains/parked.json");
require("domains/otherstuff.json");

{% endcode %}

Example 2: Complex

Here's a more complex example:

{% code title="dnsconfig.js" %}

require("kubernetes/clusters.js");

D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
    IncludeKubernetes()
);

{% endcode %}

{% code title="kubernetes/clusters.js" %}

require("./clusters/prod.js");
require("./clusters/dev.js");

function IncludeKubernetes() {
    return [includeK8Sprod(), includeK8Sdev()];
}

{% endcode %}

{% code title="kubernetes/clusters/prod.js" %}

function includeK8Sprod() {
    return [
        // ...
    ];
}

{% endcode %}

{% code title="kubernetes/clusters/dev.js" %}

function includeK8Sdev() {
    return [
        // ...
    ];
}

{% endcode %}

Example 3: JSON

Requiring JSON files initializes variables:

{% code title="dnsconfig.js" %}

var domains = require("./domain-ip-map.json")

for (var domain in domains) {
    D(domain, REG_MY_PROVIDER, PROVIDER,
        A("@", domains[domain])
    );
}

{% endcode %}

{% code title="domain-ip-map.json" %}

{
    "example.com": "1.1.1.1",
    "other-example.com``": "5.5.5.5"
}

{% endcode %}

Notes

require() is much closer to PHP's include() function than it is to node's require().

Node's require() only includes a file once. In contrast, DNSControl's require() is actually an imperative command to load the file and execute the code or parse the data from it. For example if two files both require("./tools.js"), then it will be loaded twice, whereas in node.js it would only be loaded once.