Migrating and Redirecting Subdomains with Netlify

There is lots of information out there on migrating entire domains with Netlify, but less for migrating from one subdomain to another on the same host (main) domain. I wanted to put this post out there to confirm that that this is possible, and actually easy to do with Netlify Redirects.

The Old Way

Normally, If I wanted to migrate from one subdomain to another, with a site I’m hosting myself, the process might look something like:

1. Create new subdomain entry through CPanel
2. Add new DNS CNAME record for new subdomain, pointing to host
   • Depending on your host, adding the subdomain in previous step might automatically do this
3. After DNS has propagated, implement 301 redirect from old subdomain to new subdomain
   • This can be done in CPanel, with a wildcard redirect

With Netlify Redirects and Hosting

With Netlify as the host, this works a little differently.

I already had a CNAME entry pointing old-subdomain.example.com to Netlify. I added another one to point new-subdomain.example.com to the same Netlify host, but then had to sit and think for a second about the best way to move forward.

• In order to use CPanel redirect settings for a subdomain, my host requires that the subdomain exist as a CPanel subdomain entity. This means it gets its own folder and CNAME entries
• For redirecting the old subdomain, this didn’t really make sense; I don’t want it as a CPanel subdomain, because I’m not doing any hosting – it is still Netlify. Furthermore, CPanel wouldn’t even let me create it as a subdomain, since I still had a CNAME entry for it pointing to Netlify, and the CPanel workflow won’t allow the creation of a duplicate.
• Theoretically, I could remove the CNAME for the old subdomain that points to Netlify, create a host folder, and then implement redirects to the new one, but that seems overly complicated…

Solution

A much cleaner solution emerged seconds later, and within minutes, I had everything live and working flawlessly. Here are the steps I ended up taking

IMPORTANT: Do not delete the old subdomain CNAME entry pointing to Netlify!

1. Create new CNAME entry, pointing new-subdomain.example.com to Netlify (Netlify Docs: Subdomains)
2. Go to Netlify -> Project -> Site Settings -> Domain Management, and add new subdomain as alias. Once DNS change from step 1 is working, you can set it as the primary domain.
3. ✨ Use the Netlify special _redirects file to 301 redirect all pages from the old subdomain to the new one (Docs: Redirects) (see below for example). Push it live.

_redirects file:

# Redirect old subdomain to new one
https://old-subdomain.example.com/* https://new-subdomain.example.com/:splat 301!

And… that’s it 🤯! Seriously! No messing with CPanel subdomains or HTACCESS files! 😅

All the redirection is handled directly by Netlify, and as long as we don’t delete our old CNAME entry, visitors can still follow links to our old subdomain and get 301 redirected to the same page on the new one. There might be a noticeable dip in organic traffic, but it should only be momentary, as Google and other search engines respect 301 redirects and should very quickly recognize your new subdomain as legitimate.

Reminder

As with any domain migration, don’t forget to also update:

• Analytics settings (Google Analytics, etc.)
• Hard-coded internal links, and external links you have access to
• Config files (e.g. siteUrl setting in gatsby-config.js)
• Any where else the hardcoded URL might be used (email signatures, LinkedIn, etc.)