Where Are .is-a.dev Domain Configurations Stored? A Complete Guide to the Register Repository

The .is-a.dev domain configurations are stored as individual JSON files in the domains/ directory of the is-a-dev/register repository, with each file named after the specific subdomain and containing DNS records that are loaded at runtime by the dnsconfig.js module.

The is-a-dev/register repository powers the free .is-a.dev subdomain service, allowing developers to register custom subdomains for their projects. Understanding where these .is-a.dev domain configurations reside and how they are structured is essential for contributors and users managing their DNS records.

The domains/ Directory: Storage Location for All Configurations

Every registered .is-a.dev subdomain has a dedicated configuration file located in the domains/ folder at the repository root. This directory acts as the central registry, containing thousands of JSON files that collectively define the DNS behavior for the entire domain space.

JSON File Structure and Naming Convention

Each configuration file follows a strict naming convention: the filename matches the subdomain name with a .json extension. For example, the subdomain example.is-a.dev corresponds to domains/example.json.

The file content is a JSON object containing a records array that defines the DNS records:

{
  "records": [
    {
      "type": "A",
      "value": "192.0.2.1"
    },
    {
      "type": "CNAME",
      "value": "username.github.io"
    },
    {
      "type": "TXT",
      "value": "v=spf1 include:_spf.google.com ~all"
    }
  ]
}

DNS Record Types Supported

The .is-a.dev domain configurations support standard DNS record types within the JSON structure:

• A Records: Point subdomains to IPv4 addresses
• AAAA Records: Point subdomains to IPv6 addresses
• CNAME Records: Alias one subdomain to another
• TXT Records: Store text information for verification or SPF records
• MX Records: Define mail servers for the subdomain

How dnsconfig.js Orchestrates Configuration Loading

While the domains/ directory stores the static configuration data, the dnsconfig.js file at the repository root contains the runtime logic that reads and serves these configurations. This module acts as the bridge between the stored JSON files and the live DNS infrastructure.

When a DNS query arrives for a specific subdomain, the system uses dnsconfig.js to locate and parse the corresponding file in the domains/ directory. The module validates the JSON structure and extracts the records array to formulate the DNS response.

Loading Domain Configurations Programmatically

Below is a practical example demonstrating how the registry loads a specific subdomain configuration, mirroring the logic found in dnsconfig.js:

import fs from "fs";
import path from "path";

/**
 * Retrieve the DNS configuration JSON for a specific .is-a.dev subdomain.
 * @param {string} subdomain – e.g. "example" for example.is-a.dev
 * @returns {object} Parsed DNS configuration
 */
export function getDomainConfig(subdomain) {
  const filePath = path.join(
    import.meta.dirname,
    "domains",
    `${subdomain}.json`
  );

  // The file contains an object like { "records": [ { "type": "A", "value": "1.2.3.4" } ] }
  const raw = fs.readFileSync(filePath, "utf-8");
  return JSON.parse(raw);
}

// Usage
const config = getDomainConfig("example");
console.log(config);

Key Files in the Repository Architecture

Understanding the .is-a.dev domain configurations requires familiarity with these critical files:

• domains/ – The directory containing one JSON file per registered subdomain (e.g., example.json, 1234567890.json). This is the primary storage location for all DNS data.
• dnsconfig.js – The core module that loads and serves the JSON records for incoming DNS queries, defining the default DNS handling logic.
• README.md – General project documentation explaining how to register new subdomains and the structure of configuration files.
• package.json – Lists Node.js dependencies and scripts used by the registry server to process domain configurations.

Summary

• The domains/ directory stores every .is-a.dev subdomain configuration as an individual JSON file named after the subdomain.
• Each JSON file contains a records array defining DNS entries (A, CNAME, TXT, MX, etc.).
• The dnsconfig.js module reads these JSON files at runtime to serve DNS responses for incoming queries.
• File naming follows the pattern domains/{subdomain}.json, making it easy to locate specific configurations programmatically.

Frequently Asked Questions

What format are the domain configuration files in?

The .is-a.dev domain configurations use JSON format. Each file contains a top-level object with a records property that holds an array of DNS record objects. Each record specifies a type (such as A, CNAME, or TXT) and a value containing the DNS data.

How does the system handle multiple DNS records for one subdomain?

The JSON structure supports multiple records by storing them as separate objects within the records array. For example, a single subdomain can have both an A record pointing to an IP address and a TXT record for verification purposes, all defined within the same domains/{subdomain}.json file.

Can I manually edit my domain configuration file?

Yes, you can modify your configuration by submitting a pull request to the is-a-dev/register repository. You need to edit the specific JSON file located in the domains/ directory that corresponds to your subdomain. Changes are validated by the maintainers and the dnsconfig.js logic before being merged and deployed to the DNS infrastructure.

Where is the logic that reads these configuration files?

The runtime logic resides in dnsconfig.js at the repository root. This module imports the JSON files from the domains/ directory and processes them to generate DNS responses. It handles the mapping between incoming DNS queries and the specific configuration files stored in the repository.

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