How to Migrate from Netlify Functions to Gatsby Functions on Gatsby Cloud

Paul Scanlon
Paul Scanlon
April 6th, 2022

As you may already know, Gatsby’s had Serverless Functions since v3.7 (June 2021). Prior to this release, you may have implemented Netlify Functions. In this post I’ll explain how to migrate from Netlify Functions hosted on Netlify to Gatsby Functions hosted on Gatsby Cloud.

If you’re keen to jump ahead I’ve prepared a demo repo. The main branch is where you can see how I’ve implemented Netlify Functions which are hosted on Netlify, and a PR where I’ve migrated to Gatsby Functions that will work out of the box when deployed to Gatsby Cloud.

Upgrade Gatsby

Ensure you’re on at least Gatsby v3.7

Remove Netlify Plugins

Uninstall both the Netlify specific plugins. Gatsby Functions work out of the box from v3.7.

Remove Plugin from gatsby-config.js

Remove the plugin from gatsby-config.js as you’ll no longer be using it.

Remove Plugin from netlify.toml

Remove the plugin from netlify.toml as you’ll no longer be using it.

Move location on disk

Netlify functions will typically be located at the root of your project in a directory named: netlify/functions. Gatsby functions are located in src/api.

Refactor Functions

In my PR it’s a little difficult to see the diff because I’ve moved the location of the functions. Here’s a demonstration purposes only PR which shows the diff a little more clearly.

Or if you prefer, here’s the same diff.

Client Side Request

To make client side requests to Gatsby Functions change the path so it starts with /api/.

Scripts

Gatsby Functions will work when running the usual gatsby develop script so you can remove any Netlify specific start scripts from package.json.

There are some older implementations for Netlify Functions. Depending on when you implemented them you might be looking at a slightly different starting point. 

If you were using the netlify-lambda the steps above might be slightly different, but to summarize, the general migration pattern is:

  • Uninstall all Netlify specific plugins or packages
  • Remove any reference to Netlify plugins in gatsby-config.js and/or
  • Remove any reference to Netlify plugins in netlify.toml
  • Move the location on disk of function files to src/api
  • Refactor Functions to use Gatsby’s “express like” syntax
  • Rename the paths used in any client side request
  • Remove all Netlify specific start scripts

..and that’s it, less config is always a good thing right! 

If you’d like any more info on Gatsby Functions feel free to come find me on Twitter: @PaulieScanlon.

Paul Scanlon
Written by
Paul Scanlon

After all is said and done, structure + order = fun! Senior Software Engineer (Developer Relations) for Gatsby

Follow Paul Scanlon on Twitter

Talk to our team of Gatsby Experts to supercharge your website performance.