I host all my sites on Netlify (you can read about how I do this in How I scale my sites to 500k* users per month for free*) and used to use the domain iamhamy.xyz but recently decided that I wanted to use hamy.xyz instead since it was shorter and more to the point. This meant that I needed to migrate 4 sites that I hosted on Netlify to a new domain:
Doing this naively is pretty simple, you would just redirect the iamhamy.xyz domains to point to the hamy.xyz domains and be done with it. But the naive way has some drawbacks - 1) it’s not guaranteed that each url from the old site will correctly redirect to the new url on the new site and 2) many search engines will see that the old url doesn’t exist since the old url goes to the new url and trash any SEO / PageRank you’ve built up over the years (this is how Google indexes your site and decides what to show users). 1) could break the site for users / leave them with a bad experience and 2) could keep users from finding your site in the first place. I’ve built up an audience of around 5k users / month over a couple years, so these are things I’d like to avoid.
The solution to this problem is to use proper redirects. Redirects, when done correctly, allow you to map your old urls to the new urls so that you send users to the correct place and tell search engines that your content has moved so that they can transfer any PageRank / indexing over to your new content. In this post, I’ll talk about how I migrated my Netlify sites without harming my PageRank / SEO.
The first thing to understand is the basics of SEO / PageRank as this is the mechanism by which search engines index what content you have, how authoritative it is, and ultimately decide what to show users. It’s key to having a findable website. At its core it relies on two things:
So as we go through the migration it’s important that we keep our old links alive and have them point to the new links where the content now lives so that search engines can see that the backlinks still work and we can maintain that ‘popularity’.
The internet way of telling visitors that something has moved is to use a redirect http code. The most common ones are:
Here’s a list of all http codes.
My migration from iamhamy.xyz -> hamy.xyz is meant to be permanent, so I went with 301. The way this works in practice is that you’d have all old urls return an http response with the redirect code and the url to the new page. So you could imagine that for my about page iamhamy.xyz/about, I’d return something like:
There are multiple ways to do this but that’s the gist of it.
Now that we understand the basics of SEO / PageRank and how to tell visitors that we’ve moved we can move onto implementing redirects with Netlify.
One of the reasons I love Netlify is that it’s simple and just works. Redirects are no different.
In a typical migration, you need to have 1) a mapping of old urls to new urls, 2) a way for old urls to return an http redirect to the new url, and 3) your new site up and running. Depending on what tools are at your disposal and your implementation stack, this could be as easy as a server config change or as tedious as needing to set up a whole new site just for redirects.
The whole migration with Netlify biases towards the easy side requiring just a few domain configurations and a single redirect configuration code push. Here are the steps:
Now if you’re migrating sites from one domain to another, you’re going to need to own the domain that you’re migrating to. I’ll trust you to know or Google how to do this yourself.
The Netlify method of migrating doesn’t require setting up a new website. So the first step is to just make your domain point to the correct website.
There are two ways to do this 1) allow Netlify to do the domain configuration for you or 2) configure your domain manually. Both require at least a little bit of configuration so it’s really up to you to decide how you want to go about this.
1) allow Netlify to do the domain configuration for you
At this point, Netlify will be able to control some domain configurations for you. Now we just need to tell Netlify what domains should go where.
2) configure your domain manually
This one is a little less work but requires you to know a little bit more about domain configuration. We’re going to assume that you’re updating the domain configuration directly in your domain registrar here and note that each registrar may have slightly different ways to get to the domain configuration but the configuration itself will be largely the same regardless of what you’re using.
For each site you want to point this domain to:
Custom domainslist. This is typically formed like random-words-123blah.netlify.app.
Regardless of which choice you took, you should now have your domain set so that it’s pointing to Netlify. There’s a little more configuration we should do to get it properly pointed to each site (and so that netlify can configure https for us).
For each site you want to point the new domain to:
Add domain alias
Custom domainslist now and be greyed out which indicates it’s not configured yet.
Read the official docs for assigning a custom domain with Netlify
Once you’re able to get to your site via your new domain, we’ve completed this step!
So at this point, we’ve got our new domains pointing to our sites. All that’s left is to have our old domains point to our new domains and to tell search engines that we’ve done this permanently so they maintain our popularity (SEO / PageRank).
Netlify makes this super easy with their redirect options. I went with the Netlify config option via
netlify.toml because I didn’t have an easy way to get the
_redirects file into the top level of my publish directory so I’m only walking through that, but know that there are more options.
netlify.toml is a configuration file that Netlify will read from to know how you want it to serve your sites. This is called configuration in code.
To add a redirect from your old domain to your new domain, you can use something like:
[[redirects]] from = "https://labs.iamhamy.xyz/*" to = "https://labs.hamy.xyz/:splat" status = 301 force = true
from field says that we are trying to redirect requests that come in on this domain. You can use relative domains as well (like
/blog/) but since we’re migrating to new domains in this post, I’m using absolute domain redirects.
You’ll notice that I am using an
* at the end of my url. This is a wildcard and in this case means that I want to match any requests that start with
to field says where we want to send these requests. So if I have a request matching the
from field, where do I want them to go. Since I’m migrating from labs.iamhamy.xyz to labs.hamy.xyz, I put labs.hamy.xyz in the to field.
You’ll notice that I have the
:splat denotation at the end of my
to url. This means to take whatever was in the wildcard of the
from field and place it in the
:splat field. So if a request came in at labs.iamhamy.xyz/projects, this setup would make it redirect to labs.hamy.xyz/projects.
status field is the http code you want to return. Recall that http code 301 means a permanent redirect. I’m moving my sites permanently so I want to let any visitors know that.
force option is whether you want to make all requests that match the
from field go to the
to field or whether you only want to redirect those requests where no content is found in the
from field first. Since we’re trying to migrate domains, we want to send all requests to the new domain so this should be
Once you’ve added and pushed your redirect entry to each of your sites, you should once again test that each one is going where you think it should by navigating to the old domain in your browser and verifying it sends you to the new domain and that you land on the right page.
The last thing to do is to go to each site’s
domain settings and to set your new domain as the primary domain. This step doesn’t matter in most cases but is a nice cleanup thing and Netlify does do some default configuration for apex domains so it’s nice to do. You can do this by clicking the
Options dropdown and selecting
Set as primary domain
That’s it! You’ve now successfully migrated your site from one domain to another without affecting your SEO / PageRank!
I’ll call out that you should likely hold onto your old domain for awhile and keep it configured as-is so that you continue to catch visitors that don’t know about the new url and redirect them there. Personally, I plan to hold onto this old domain for at least a year to limit my exposure to this issue but it’s really up to you.
Let me know how your migration goes and anything I can do to improve this guide!
Hi I'm Hamilton and I wrote / built this! I like doing lots of things, but mostly I like to build (and then share those buildings). Some things I'm currently building: art, software, and prose. To stay up-to-date with my latest buildings, subscribe to my email list or follow one of my many other accounts. #buildit #shipit #justhamit