Getting Started

Gatsby Functions help you build Express-like backends without running servers.

Functions are generally available in sites running Gatsby 3.7 and above.

Introduction

JavaScript and TypeScript files in src/api/* are mapped to function routes like files in src/pages/* become pages. So src/api is a reserved directory for Gatsby. Gatsby by default ignores test files (e.g. hello-world.test.js) and dotfiles (e.g. .prettierrc.js).

For example, the following Function is run when you visit the URL /api/hello-world

A Function file must export a single function that takes two parameters:

• req: Node’s http request object with some automatically parsed data
• res: Node’s http response object with some extra helper functions

Dynamic routing is supported for creating REST-ful APIs and other uses cases

• /api/users => src/api/users/index.js
• /api/users/23 => src/api/users/[id].js

Learn more about dynamic routes.

Typescript

Functions can be written in JavaScript or Typescript.

Common data formats are automatically parsed

Query strings and common body content types are automatically parsed and available at req.query and req.body

Read more about supported data formats for information about support for Buffer and Stream via a custom config.

Respond to HTTP Methods

Sometimes you want to respond differently to GETs vs. POSTs or only respond to one method.

Headers

Only HTTP headers prefixed with x-gatsby- are passed into your functions.

Environment variables

Site environment variables are used to pass secrets and environment-specific configuration to Functions.

Forms

Forms and Functions are often used together. For a working example you can play with locally, see the form example. The Forms doc page is a gentle introduction for building forms in React. Below is sample code for a very simple form that submits to a function that you can use as a basis for building out forms in Gatsby.

Functions in plugins and themes

Plugins and themes can ship functions! This is powerful as it lets you pair frontend code with backend code. For example, if you built a plugin for an authorization service that includes a login component, you could ship alongside the component, a serverless function the component can use to connect to the remote API.

Namespacing

Plugin/theme functions work exactly the same as normal functions except their routes must be created under the plugin’s namespace e.g. ${PLUGIN_ROOT}/src/api/{pluginName}/my-plugin-function.js.

Shadowing with functions works similar to how shadowing works in general. You can shadow a plugin/theme function by copying the file from the plugin/theme’s src tree into your site’s src tree. For example, to shadow the /gatsby-plugin-cool/do-something function from the gatsby-plugin-cool plugin, you’d copy node_modules/gatsby-plugin-cool/src/api/gatsby-plugin-cool/do-something.js to src/api/gatsby-plugin-cool/do-something.js. From there, you can overwrite the implementation of the /do-something function as you normally would.

Limitations

• Bundling in native dependencies is not supported at the moment.
• Creating your own custom bundler (webpack/parcel) config is not supported at the moment. You can however pre-bundle by using a “prebuild” package.json script command to accomplish custom configuration.