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

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

npm install gatsby@latest // yarn add gatsby@latest

Remove Netlify Plugins

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

npm uninstall gatsby-plugin-netlify @netlify/plugin-gatsby // yarn remove gatsby-plugin-netlify @netlify/plugin-gatsby

Remove Plugin from gatsby-config.js

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

gatsby-config.js

module.exports = {
  siteMetadata: {
    title: ''
  },
  plugins: [
-     'gatsby-plugin-netlify'
    ]
  }
};

Remove Plugin from netlify.toml

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

netlify.toml

[[plugins]]
-  package = "@netlify/plugin-gatsby"

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.

test-function.js

- exports.handler = async function (event, context) {
-  return {
-    statusCode: 200,
-    body: JSON.stringify({ message: 'A ok! ' })
-  };
- };
+ export default async function handler(req, res) {
+   res.status(200).json({
+    message: 'A ok!'
+  });
+ }

Client Side Request

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

index.js

- const response = await fetch('/.netlify/functions/test-function');
+ const response = await fetch('/api/test-function');

Scripts

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

package.json

"scripts": {
  ...
  "develop": "gatsby develop",
-  "start": "netlify dev",
}

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.

Share on Twitter Share on LinkedIn Share on Facebook Share via Email