How Domains Work with Headless Cmssy

Cmssy is a headless CMS with a visual editor. Your content lives in the Cmssy admin and is served over the delivery API, while your actual website is a Next.js (App Router) app you build with @cmssy/react and @cmssy/next and deploy yourself (for example on Vercel). Cmssy does not host your site.

Because you own the deployment, your custom domain points at your host, not at Cmssy. You add the domain wherever your site is deployed, configure DNS at your registrar, and your host issues the SSL certificate. On the Cmssy side, you set the workspace Preview URL so the editor frames your deployed site for visual editing.

Why Use a Custom Domain

Using a custom domain for your headless site offers several important benefits:

• Professionalism — A custom domain like yourcompany.com looks far more professional than a default deployment URL. It shows visitors you're serious about your online presence.
• Branding — Your domain is part of your brand identity. A memorable domain reinforces brand recognition every time someone visits or shares your URL.
• SEO Benefits — Search engines favor established custom domains. Over time, your domain builds authority and improves your ranking in search results.
• Email Matching — With a custom domain, you can use matching email addresses (e.g., hello@yourcompany.com) for a consistent and trustworthy brand experience.

Prerequisites

Before you begin, make sure you have:

• A deployed Cmssy site — A Next.js app wired to your workspace with @cmssy/react and @cmssy/next. See the installation guide and quickstart if you haven't deployed yet.
• A hosting account — Wherever you deployed your site (e.g., Vercel). Custom domains and SSL are handled there.
• A domain registered with any registrar — You can use Cloudflare Registrar (at-cost pricing), Namecheap, Porkbun, or any other domain registrar.

Step 1: Deploy Your Headless Site

Before attaching a domain, make sure your site is built and deployed:

1. Build your Next.js app with Cmssy blocks using @cmssy/react and @cmssy/next.
2. Deploy it to your host (for example, push to a Git repo connected to Vercel).
3. Confirm the deployment is live at its default URL (e.g., your-site.vercel.app).

This deployed app is what your custom domain will point to.

Step 2: Add Your Domain on Your Host

In your hosting provider's dashboard (Vercel used as an example):

1. Open your project and go to Settings → Domains.
2. Click Add and enter your domain name, for example: example.com.
3. Add the www variant as well if you want it: www.example.com.

Your host will then show the exact DNS records you need to configure in the next step.

Step 3: Configure DNS Records

Go to your domain registrar's DNS management panel and add the records your host gave you. For Vercel, these typically look like:

The CNAME record for www points your www subdomain at your host. The A record for the root domain (@) points the apex at your host's IP. Always use the exact values shown in your host's dashboard — they can differ between providers and over time.

Step 4: Verify the Domain

After adding the DNS records:

1. Return to the Domains section in your host's dashboard.
2. Your host checks the records automatically and marks the domain as valid once they resolve.

DNS propagation may take up to 48 hours, but in most cases it completes within 15–30 minutes. If the domain shows as invalid, wait a bit longer and re-check.

Step 5: SSL Certificate

Once your domain resolves, your host provisions SSL automatically — Cmssy is not involved in this step:

• Automatic SSL provisioning — Hosts like Vercel issue a certificate (e.g., via Let's Encrypt) for your domain.
• HTTPS enabled by default — All traffic is automatically redirected to HTTPS.
• No manual configuration needed — Certificate renewal is handled by your host.

Your site will be accessible via https://yourdomain.com within minutes of the domain resolving.

Step 6: Set the Cmssy Preview URL

So the visual editor frames the right site, point Cmssy at your live domain:

1. Log in to your Cmssy admin dashboard.
2. Go to Settings → Headless.
3. Set the Preview URL to your deployed site (e.g., https://yourdomain.com).

Now the Cmssy editor loads your deployed site for in-context visual editing while content continues to be served by the delivery API.

Common DNS Providers

Here are brief instructions for popular domain registrars. In every case, use the exact record values your host provides.

GoDaddy

1. Go to My Products → select your domain → DNS.
2. Click Add Record and enter the CNAME and A records from your host.
3. Save changes.

Namecheap

1. Go to Domain List → click Manage next to your domain.
2. Select the Advanced DNS tab.
3. Add the CNAME and A records.
4. Save all changes.

Cloudflare

1. Select your domain in the Cloudflare dashboard.
2. Go to DNS → Records.
3. Add the CNAME record with DNS only mode (grey cloud icon — not proxied).
4. Add the A record.

Porkbun

1. Go to Account → Domain Management → select your domain.
2. Open the DNS Records editor.
3. Add the CNAME and A records.
4. Save.

Troubleshooting

Domain Not Resolving

• Check DNS propagation — Use tools like dig or nslookup in your terminal, or online tools like whatsmydns.net, to confirm your records have propagated.
• Confirm the values match your host — Double-check the CNAME/A values against what your host's Domains panel shows.
• Wait longer — Propagation can take up to 48 hours in rare cases. Be patient.

SSL Issues

• Conflicting CDN proxy — If you're using Cloudflare in proxy mode, it may conflict with your host's SSL provisioning. Switch to DNS-only mode so your host can issue the certificate.

WWW vs Root Domain

• Both www.example.com and example.com should be configured on your host. Add both the CNAME (for www) and A record (for root) so visitors can reach your site regardless of which URL they use.

Editor Shows the Wrong Site

• If the Cmssy editor frames an old or default URL, update the Preview URL under Settings → Headless to your live domain.

Best Practices

• Always configure both www and root — This ensures visitors can access your site from either URL variant.
• Set up email separately — Custom domain email (e.g., via Google Workspace or Zoho) requires separate MX records and won't conflict with the DNS records pointing your site at your host.
• Use DNS-only mode if using Cloudflare — Cloudflare's proxy mode can interfere with your host's SSL certificates. Use the grey cloud (DNS-only) for records pointing to your host.
• Keep the Preview URL in sync — Whenever your production domain changes, update the Preview URL under Settings → Headless so the editor keeps framing the right site.