Migrating static redirects from Gatsby Cloud to Vercel

Since Gastby Cloud is being discontinued in favor of Netlify's offering, I was looking for a new home for my personal website, which was hosted using Gatsby Cloud's free tier.

The suggested migration path logically led to Netlify, but since I already hosted some other sites via Vercel, I wanted to try that option first. Luckily, Vercel has built-in support for Gatsby.

The migration was mostly a simple matter of linking my GitHub repository to a new Vercel project, bulk-copy-pasting environment variables, and clicking "Deploy", however, there was just one thing didn't work out-of-the-box: static redirects.

I couldn't find specific migration documentation on this, but it wasn't hard to figure out either. Hence this short writeup!

Recap: redirects in Gatsby Cloud

Redirects in Gatsby Cloud were made available through the plugin gatsby-plugin-gatsby-cloud. In your gatsby-node.{js,ts}, this plugin interacted with the createRedirect action. Wildcard replace rules were also supported:

exports.createPages = ({ actions }) => {
  const { createRedirect } = actions

  createRedirect({
      fromPath: "/posts/*",
      toPath: "/articles/*",
  })

}

Static redirects in Vercel

In contrast to Gatsby Cloud, Vercel does not seem to automagically transform createRedirect calls during the SSG build stage into runtime redirections.

Instead, Vercel understands a configuration file called vercel.json in the root of your repository, which can be used to configure Vercel's build & runtime behavior for a static site.

It also allows you to specify redirects, including wildcard replacement rules. The example above can be encoded as follows in vercel.json:

{
  "redirects": [
    {
      "source": "/posts/:path*",
      "destination": "/articles/:path*"
    }
  ]
}

So, to migrate:

1. Transform the format of your rules into Vercel's JSON format (see docs). If you have many rules, you can use tools like VSCode regex search/replace, multi-cursor editing, or GNU sed to automate this process.
2. Put those rules in vercel.json at the root of your repository.
3. Remove all traces of createRedirect() from your code, remove gatsby-plugin-gatsby-cloud from your gatsby.config.js, and remove the plugin package using your package manager.

That's all there is to it!