Gatsby + Fastify


Gatsby plugin for easy integration with Fastify.

MIT License NPM version npm peer dependency version npm peer dependency version


gatsby-plugin-fastify gives you a way to integrate your Gatsby site with a Node.js server using Fastify. Use to serve a standard Gatsby.js site normally - the plugin will take care of everything:


Install the plugin using npm or yarn

npm install gatsby-plugin-fastify fastify

and add it to your gatsby-config.js

module.exports = {
  /* Site config */
  plugins: [
    /* Rest of the plugins */
      resolve: `gatsby-plugin-fastify`,
      /* Default option value shown */
      options: {
        compresion: true; //When set to false gzip/bz compression assets is disabled.

Serving your site

Node and Fastify are great for building application specific web servers but generally should not be used on the edge. Meaning, most folks will use a fully fledged web server (e.g. Nginx or Caddy that handles traffic before passing it back to node. This allows the Edge web server to handle security, TLS/SSL, load balencing, etc. Then the node server only worries about the application. A CDN (e.g. Fastly or CloudFlare ) is also often used for performance and scalability.

Server CLI (expected)

This plugin implements a server that’s ready to go. To use this you can configure a start(or whatever you prefer) command in your package.json:

  "scrips": {
    "start": "gserve"

CLI Config

  -p, --port  Port to run the server on              [number] [default: "8080"]
  -h, --host  Host to run the server on         [string] [default: ""]
  -o, --open  Open the browser                       [boolean] [default: false]

      --help      Show help                                           [boolean]
      --version   Show version number                                 [boolean]
  -l, --logLevel  set logging level
         [string] [choices: "trace", "debug", "info", "warn", "error", "fatal"]
                                                              [default: "info"]

All settings may be change via environment variables prefixed with GATSBY_SERVER_ and the flag name.

# For example:


By default only basic info is logged along with warnings or errors. By setting the logging level to debug you’ll also enable Fastify’s default request logging which is usually enabled for the info level.

Gatsby Fastify Plugin (advanced)

This plugin also implements a Fastify plugin for serving Gatsby. This may be imported via:

import { serveGatsby } from "gatsby-plugin-fastify/plugins/gatsby";

For an example on how to use this, reference the server implementation file from src/serve.ts.

Gatsby Feature Fastify Plugins (expert)

Finally, each of the Gatsby features (functions, static files, redirects, client-only routes, and 404 handling) is implemented in it’s own plugin. Those may be imported as well for use in a custom server implementation.

import { handle404 } from "gatsby-plugin-fastify/plugins/404";
import { handle500 } from "gatsby-plugin-fastify/plugins/500";
import { handleClientOnlyRoutes } from "gatsby-plugin-fastify/plugins/clientRoutes";
import { handleFunctions } from "gatsby-plugin-fastify/plugins/functions";
import { handleRedirects } from "gatsby-plugin-fastify/plugins/redirects";
import { handleStatic } from "gatsby-plugin-fastify/plugins/static";
import { handleServerRoutes } from "gatsby-plugin-fastify/plugins/serverRoutes";

For an example on how to use these, see the serveGatsby implementation file from src/plugins/gatsby.ts.

Gatsby Functions

Gatsby’s function docs suggest that the Request and Response objects for your Gatsby functions will be Express like and provide the types from the Gatsby core for these.


Because we’re not using Express or Gatsby’s own cloud offering functions will need to use Fastify’s own Request and Reply API.

If you’d like to use Fastify with an Express like API there are plugins for Fastify to do this, see their docs on middleware. You’ll need to use the exports provided in this package to write your own server implementation and add the correct plugins to support this.


import type { FastifyRequest, FastifyReply } from "fastify";

export default function handler(req: FastifyRequest, res: FastifyReply) {
  res.send(`I am TYPESCRIPT`);