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.
- Main Branch | Netlify Functions: https://github.com/PaulieScanlon/gatsby-migrate-netlify-functions
- PR Branch | Gatsby Functions: https://github.com/PaulieScanlon/gatsby-migrate-netlify-functions/pull/1/files
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.jsand/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.