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

Functions are generally available in sites running Gatsby 3.7 and above. Learn more and join the discussion.

Hello World

JavaScript and Typescript files in src/api/* are mapped to function routes like files in src/pages/* become pages.

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:

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.

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.

Limitations

  • Gatsby Functions do not support dynamic routes in Gatsby Cloud at the moment
  • Bundling in native dependencies is not supported at the moment