How CNAME Records Are Handled for Apex Domains in is-a.dev

is-a.dev does not create CNAME records at the zone apex; instead, the DNS configuration script converts subdomain CNAME entries to Cloudflare ALIAS records and explicitly ignores any configuration attempts for the root domain via the IGNORE("@", "*") directive in dnsconfig.js.

The is-a-dev/register repository automates DNS provisioning for the is-a.dev domain using Cloudflare. Understanding how the system handles CNAME records for apex domains is crucial for users attempting to configure root-level redirects, as the architecture programmatically prohibits traditional CNAME records at the zone apex.

The Technical Constraint: No CNAME at the Apex

DNS specifications strictly prohibit CNAME records at the zone apex (the root domain) because a CNAME cannot coexist with other mandatory record types like NS or SOA. Since is-a.dev uses Cloudflare as its DNS provider, the project enforces this restriction to maintain zone integrity. The system explicitly rejects any attempt to define records for the @ label, ensuring compliance with DNS standards while preventing configuration errors.

How Subdomain CNAMEs Are Converted to ALIAS Records

When you define a CNAME record in a subdomain JSON file, the dnsconfig.js script does not create a traditional CNAME. Instead, it generates a Cloudflare ALIAS record, which provides similar functionality without violating DNS constraints.

In dnsconfig.js at line 53, the script processes CNAME entries as follows:

records.push(ALIAS(subdomainName, data.records.CNAME + ".", proxyState));

This conversion allows the subdomain to point to an external hostname while remaining compatible with Cloudflare's proxy and DNS infrastructure.

Explicit Apex Domain Exclusion

The system explicitly blocks any DNS records for the apex domain using the IGNORE directive. In dnsconfig.js at line 152, the configuration contains:

IGNORE("@", "*"),

This rule instructs the DNS compiler to disregard any record definitions for the @ label (the root domain), effectively preventing users from creating domains/@.json or any other apex configuration that might attempt to set a CNAME or other record types.

Practical Configuration Examples

Valid Subdomain CNAME Configuration

Creating domains/example.json with a CNAME record:

{
  "owner": { "username": "example", "email": "example@users.dev" },
  "records": { "CNAME": "example.github.io" }
}

According to the logic in dnsconfig.js, this generates an ALIAS record mapping example.is-a.dev to example.github.io, enabling the subdomain to resolve correctly while maintaining Cloudflare proxy compatibility.

Rejected Apex Domain Configuration

Attempting to create domains/@.json to set a root CNAME:

{
  "owner": { "username": "root", "email": "root@users.dev" },
  "records": { "CNAME": "myhomepage.com" }
}

This configuration is ignored entirely due to the IGNORE("@", "*") rule at line 152. To point the apex domain elsewhere, you must use A or AAAA records instead, as these are compatible with root-level DNS configurations.

Summary

• Apex CNAMEs are prohibited: The root domain cannot have CNAME records due to DNS standards and the explicit IGNORE("@", "*") rule in dnsconfig.js at line 152.
• ALIAS records replace CNAMEs: Subdomain CNAME entries are converted to Cloudflare ALIAS records via the logic at line 53 of dnsconfig.js.
• Subdomain-only support: Only subdomains (e.g., subdomain.is-a.dev) can use the CNAME field in their JSON definitions.
• Apex requires A/AAAA records: To configure the root domain, use IP-based records rather than CNAMEs.

Frequently Asked Questions

Can I create a CNAME record for the root is-a.dev domain?

No. The is-a.dev DNS configuration explicitly ignores all records for the apex domain via the IGNORE("@", "*") directive in dnsconfig.js. DNS standards also prohibit CNAME records at the zone apex because they conflict with mandatory SOA and NS records required for proper zone operation.

What happens if I try to submit a domains/@.json file with a CNAME?

The DNS compiler will reject the configuration. According to line 152 of dnsconfig.js, the IGNORE("@", "*") rule filters out any records associated with the @ label, meaning your CNAME definition will not be published to Cloudflare and the root domain will not resolve to your target.

Why does is-a.dev use ALIAS records instead of CNAME records for subdomains?

The dnsconfig.js script at line 53 converts CNAME definitions to ALIAS records using records.push(ALIAS(subdomainName, data.records.CNAME + ".", proxyState)). This approach leverages Cloudflare's ALIAS pseudo-record type, which provides CNAME-like functionality while maintaining compatibility with Cloudflare's proxy and DNS infrastructure.

How do I point the apex domain to my server if CNAME is not allowed?

You must use A or AAAA records containing the IPv4 or IPv6 addresses of your target server. The is-a.dev registration system accepts these record types for the root domain, whereas CNAME entries are restricted to subdomains only.

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