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

> Discover how is-a.dev expertly manages CNAME records for apex domains. Learn about ALIAS record conversion and root domain configuration.

- Repository: [is-a.dev/register](https://github.com/is-a-dev/register)
- Tags: internals
- Published: 2026-03-09

---

**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`](https://github.com/is-a-dev/register/blob/main/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`](https://github.com/is-a-dev/register/blob/main/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`](https://github.com/is-a-dev/register/blob/main/dnsconfig.js) at line 53, the script processes CNAME entries as follows:

```js
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`](https://github.com/is-a-dev/register/blob/main/dnsconfig.js) at line 152, the configuration contains:

```js
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`](https://github.com/is-a-dev/register/blob/main/domains/example.json) with a CNAME record:

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

```

According to the logic in [`dnsconfig.js`](https://github.com/is-a-dev/register/blob/main/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:

```json
{
  "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`](https://github.com/is-a-dev/register/blob/main/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`](https://github.com/is-a-dev/register/blob/main/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`](https://github.com/is-a-dev/register/blob/main/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`](https://github.com/is-a-dev/register/blob/main/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`](https://github.com/is-a-dev/register/blob/main/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.