What Is dnsconfig.js in is-a.dev? The DNS Zone Build Script

dnsconfig.js is the central DNSControl configuration script in the is-a-dev/register repository that assembles subdomain definitions from JSON files and publishes the complete DNS zone to Cloudflare.

The is-a-dev/register repository provides free subdomains under is-a.dev for developers and open-source projects. At the heart of this infrastructure lies dnsconfig.js, a DNSControl configuration file that acts as the build pipeline, converting static JSON data into live DNS records on Cloudflare.

Core Responsibilities of dnsconfig.js

Zone Definition and Provider Configuration

At the top of dnsconfig.js‑L4), the script establishes the fundamental zone parameters and declares the DNS provider. It defines the domain name, a placeholder registrar, and initializes the Cloudflare provider instance that will handle the actual DNS publication.

var domainName = "is-a.dev";
var registrar   = NewRegistrar("none");
var dnsProvider = DnsProvider(NewDnsProvider("cloudflare"));

Loading Subdomain JSON Definitions

The script dynamically discovers all subdomain configurations by scanning the ./domains directory. Using the getDomainsList helper at lines L21‑L22, it imports every *.json file, each containing the record definitions for a specific subdomain.

var domains = getDomainsList("./domains");

Record Type Transformation

Between lines L24‑L136, dnsconfig.js iterates over each imported JSON object and transforms the declared records into DNSControl primitives. It handles A, AAAA, CNAME, MX, TXT, and other record types, converting JSON arrays into function calls like A(), AAAA(), or CNAME(). The script also respects the proxied boolean flag to enable or disable Cloudflare proxying via CF_PROXY_ON or CF_PROXY_OFF.

Reserved and Internal Domain Protection

To protect critical infrastructure names, lines L38‑L44 load util/reserved.json and force every reserved subdomain to resolve to the placeholder IP 192.0.2.1. This ensures that names like _acme-challenge or _github-pages-challenge-is-a-dev cannot be hijacked by user submissions, regardless of what exists in the domains/ folder.

var reserved = require("./util/reserved.json");
for (var i = 0; i < reserved.length; i++) {
    records.push(A(reserved[i], IP("192.0.2.1"), CF_PROXY_ON));
}

Ignored Records Management

Certain wildcard patterns and infrastructure records must never be published to the live zone. Lines L49‑L63 define an ignored array containing patterns like *._domainkey TXT records and ns1 through ns4 A/AAAA records. DNSControl uses this list to purge matching entries before publication.

Zone Publication to Cloudflare

Finally, at line L70, the script invokes the DNSControl D() function, passing the assembled domain name, registrar, provider, records array, and ignored patterns. This single call triggers the API interaction that synchronizes the entire zone with Cloudflare's edge network.

D(domainName, registrar, dnsProvider, records, ignored);

How dnsconfig.js Transforms JSON to DNS Records

When you submit a new subdomain via a JSON file in the domains/ directory, dnsconfig.js compiles that declaration into executable DNSControl code. For example, creating domains/example.json with the following content:

{
  "records": {
    "A": ["203.0.113.42"],
    "TXT": ["v=spf1 -all"]
  },
  "proxied": true
}

Results in the script generating these internal record objects:

records.push(A("example", IP("203.0.113.42"), CF_PROXY_ON));
records.push(TXT("example", "\"v=spf1 -all\""));

Similarly, a CNAME configuration in domains/internalsvc.json:

{
  "records": {
    "CNAME": "internal.is-a.dev"
  },
  "proxied": false
}

Produces an ALIAS record with proxying disabled (as implemented around lines L88‑L122):

records.push(ALIAS("internalsvc", "internal.is-a.dev.", CF_PROXY_OFF));

Key Files in the is-a.dev DNS Pipeline

• dnsconfig.js: The main orchestration script that defines the zone, loads subdomain JSON, transforms records, and publishes to Cloudflare.
• domains/*.json: Declarative per-subdomain record definitions submitted by users (A, AAAA, CNAME, MX, TXT, etc.).
• util/reserved.json: A static list of subdomains reserved for internal use or security purposes, forced to resolve to 192.0.2.1.
• util/internal.json: Definitions for service-internal subdomains (e.g., internal.is-a.dev) managed by the maintainers.
• util/raw-api.js: A utility that generates a public JSON dump of all registered subdomains for external API consumers.

Summary

• dnsconfig.js serves as the DNSControl build script for the is-a.dev zone, bridging declarative JSON data and live DNS infrastructure.
• It dynamically loads subdomain definitions from domains/ and converts them into provider-specific record objects.
• Reserved subdomains listed in util/reserved.json are automatically protected with placeholder IPs, preventing user overrides.
• The script filters out sensitive patterns via an ignored list before publishing.
• All configurations are ultimately pushed to Cloudflare through the DNSControl D() function at line L70.

Frequently Asked Questions

What DNS software does is-a.dev use to manage records?

The repository uses DNSControl, a declarative DNS configuration tool from Stack Overflow. The dnsconfig.js file is a DNSControl configuration script that compiles the repository's JSON definitions into Cloudflare API calls, enabling version-controlled, reviewable DNS changes.

How does dnsconfig.js handle reserved subdomains?

The script loads util/reserved.json at startup (lines L38‑L44) and forcibly generates an A record pointing to 192.0.2.1 with CF_PROXY_ON for every entry. This happens before user-submitted domains are processed, ensuring reserved names always resolve to the placeholder IP regardless of pull request contents.

Can I override a reserved subdomain in is-a.dev?

No. Even if you create a JSON file in domains/ matching a name listed in util/reserved.json, the hardcoded loop in dnsconfig.js will overwrite it with the placeholder IP 192.0.2.1. This design guarantees that critical infrastructure names remain under maintainer control.

What record types are supported by dnsconfig.js?

According to the transformation logic in lines L24‑L136, the script explicitly supports A, AAAA, CAA, CNAME, DS, MX, NS, SRV, TLSA, TXT, and URL records. Each type has a dedicated handling block that maps JSON values to the corresponding DNSControl function (e.g., MX(), TXT()).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}