gatsby-plugin-fastify

gatsby-plugin-fastify

Gatsby plugin for easy integration with Fastify.

About

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
• Serving DSG/SSR Routes
• Gatsby 404 page
• Gatsby 500 page
• Gatsby redirects
• Gatsby reverse proxy
• Client-only routes
• Serving the site with pathPrefix - set it up inside gatsby-config.js, the plugin will take care of it
• Etags, and more.

Installation

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`,
      options: {
        /* discussed below */
      }, // All options are optional
    },
  ],
};

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 the Node server. This edge server may handle caching, TLS/SSL, load balancing, compression, 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 and may be use in place of the edge server, though this may be less secure.

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:

{
  "scripts": {
    "start": "gserve"
  }
}

CLI Config

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

Options:
      --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:
export GATSBY_SERVER_PORT=3000
export GATSBY_SERVER_HOST=0.0.0.0
# cammelCase is converted to SCREAMING_SNAKE_CASE.
export GATSBY_SERVER_LOG_LEVEL=debug

Logging

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.

For prettier logging to console set the NODE_ENV envrionment variable to development. This should not be used in production due to performance concerns. e.g.

NODE_ENV=development yarn start

Features

Some features can be disabled through the plugin options. This will not provide increased performance but is probided as an option to control features in certain deploys or to handoff certain features to an edge server or CDN as desired.

module.exports = {
  /* Site config */
  plugins: [
    /* Rest of the plugins */
    {
      resolve: `gatsby-plugin-fastify`,
      /* Default option value shown */
      options: {
        features: {
          redirects: true,
          reverseProxy: true,
          imageCdn: false, // Feature in Beta, use with caution
        },
      },
    },
  ],
};

Gatsby Image CDN (BETA)

BETA: This feature is under going active development to fix bugs and extend functionality by the Gatsby team. I'm releasing this feature here with compatability for gatsby@4.12.1, gatsby-source-wordpres@6.12.1, and gatsby-source-contentful@7.10.0 No guarantee it works on newer or older versions.

While not strictly a CDN in our case this still implements the ability for Images to be transformed outside of build time.

Please note that this writes generated images to the `/public/_gatsby folder. This must be writeable in production.

This will be enabled by default if your version of Gatsby supports the image CDN. You may manually disable it in the config if you don't need it.

Gatsby Reverse Proxy

Building on top of the createRedirects API Gatsby Cloud now supports reverse proxies. We've implemented this feature here as well.

// gatsby-node.js
createRedirect({
  fromPath: `/docs/`,
  toPath: `https://www.awesomesite.com/docs/`,
  statusCode: 200, // The 200 is required to denote a proxy response as opposed to a redirect
});

The Gatsby docs note ending the to and from paths with *. This is not allowed in this plugin. If included they are stripped for compatibility.

Gatsby Redirects

Our implementation supports several examples as shown by Gatsby Docs.

Basic, splat, wildcard, and Querystring splat redirects should all work. e.g. :

createRedirect({
  fromPath: "/perm-redirect",
  toPath: "/posts/page-1",
});
createRedirect({
  fromPath: "/redirect/:letter", // `/redirect/a`
  toPath: "/app/:letter", // `/app/a`
});
createRedirect({
  fromPath: "/redirect-query?example=:example", // `/redirect-query?example=test`
  toPath: "/app/:example", // `/app/test`
});
createRedirect({
  fromPath: "/redirect-query-query?example=:example", // `/redirect-query-query?example=test`
  fromPath: "/redirect-query-query?example=:example", // `/app?example=test`
  toPath: "/app?example=:example",
});
createRedirect({
  fromPath: "/redirect-all/*", // `/redirect-all/example`
  toPath: "/app/*", // `/app/example`
});
createRedirect({
  fromPath: "/redirect-all2/*", // `/redirect-all2/abc/124` | `/redirect-all2/abc/152`
  toPath: "/app/", // `/app/`
});

Due to router diferences we have to handle non-splat style query string redirects specially. But they cannot be combined with splat or wildcard routes e.g.

// This works
createRedirect({
  fromPath: "/redirect-query-specific?id=2",
  toPath: "/file.pdf",
});

// These worn't work
createRedirect({
  fromPath: "/redirect-query-specific?id=2&example=:example",
  toPath: "/:example/file.pdf",
});
createRedirect({
  fromPath: "/redirect-query-specific/*?id=2",
  toPath: "/*file.pdf",
});

Note: While These combos don't currently work it's not imposible to implement such a feature. If you need this feature please consider contributing.

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.

THIS IS NOT TRUE FOR THIS PLUGIN

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

TypeScript

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

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