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:

  • Serving Gatsby Functions
  • Serving static files
  • 404 page middleware
  • Gatsby redirects
  • Client-side paths
  • Serving the site with pathPrefix - set it up inside gatsby-config.js, the plugin will take care of it
  • File compression, Etags, and more.


Install the plugin using npm or yarn

npm install gatsby-plugin-fastify fastify fastify-static fastify-compress fastify-plugin fastfy-caching

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

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]
  -v, --verbose  Show verbose output                  [boolean] [default: false]

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

# For example:

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 thi 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 { handle } from "gatsby-plugin-fastify/plugins/gatsby";
import { handle404 } from "gatsby-plugin-fastify/plugins/404";
import { handleClientOnlyPaths } from "gatsby-plugin-fastify/plugins/clientPaths";
import { handleFunctions } from "gatsby-plugin-fastify/plugins/functions";
import { handleRedirects } from "gatsby-plugin-fastify/plugins/redirects";
import { handleStatic } from "gatsby-plugin-fastify/plugins/static";

For an example on how to use these you 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`);

Features you could help with

  • Support for creating pathPrefix
  • Fastify 3.x support
  • Compression support
  • Proper file caching
  • Proper CLI w/

    • flags to set port/address
  • Plugin config

    • enable/disable certain features
    • control security headers
    • control caching headers
  • Export types
  • If the site isn’t built when server is launched, build it automatically
  • Security headers/control
  • Proper testing