Gatsby adapter for Firebase

This adapter enables the following features on Firebase. Try it live at gatsbyfire.web.app.

• Redirects
• HTTP Headers
• Application of default caching headers
• Deferred Static Generation (DSG)
• Server-Side Rendering (SSR)
• Gatsby Functions
• Gatsby Image and File CDN through Firebase Hosting’s global CDN

---

• Installation
• Usage
• firebase.json
• Firebase functions
• Adapter options
• DSG and SSR functions
• Local workflows
• Limitations
• License

Installation

npm install gatsby-adapter-firebase

You will also need Firebase CLI if plan to do local deployments or use Firebase Local Emulator Suite:

npm install -g firebase-tools

Usage

Your Gatsby version must be 5.12.0 or newer, which is when adapters were introduced.

Configure Gatsby

Add the adapter to gatsby-config.js:

// gatsby-config.js
const firebaseAdapter = require('gatsby-adapter-firebase')

/** @type {import('gatsby').GatsbyConfig} */
module.exports = {
  adapter: firebaseAdapter(),
}

Build and deploy

Run a Gatsby build as usual. The adapter hooks into Gatsby’s post-build phase:

npm run build

This will either create or update your firebase.json and build .firebase/functions/ if you're using SSR, DSG, or standard functions.

Next, point your Firebase Hosting target at the desired site (once per project):

firebase --project <project-id> target:apply hosting gatsby <site-id>

Finally, deploy the project to Firebase or run locally using Firebase Local Emulator Suite:

firebase deploy
# or
firebase emulators:start --project demo-site

For local emulator setup and deployment limitations, see Local workflows.

firebase.json

During gatsby build the adapter reads firebase.json, updates the entry matching the configured Hosting target (default gatsby), and writes it back.

Key behaviors:

• Existing hosting entries for other targets are preserved.
• The adapter merges the generated config into the entry for the target, replacing its redirects, rewrites, and headers with the data derived from Gatsby.
• When Cloud Functions are produced, the functions section is merged by codebase name (default gatsby). Other codebases remain untouched.
• If the file is missing, it is created with just the generated data and other Firebase defaults.
• Other config sections are preserved.

Because this file is regenerated on every build, it is safer to keep the version committed to source control as small as possible. Track only the entries and configs you maintain by hand, ignore .firebase/, and avoid staging the adapter-generated files unless you are pinning a deliberate override.

Firebase functions

The adapter packages Gatsby Functions (SSR, DSG, and standard functions) into a Firebase Functions codebase. Functions are written to .firebase/functions. Each Gatsby function is built into a single Firebase function. If you opt for Deferred Static Generation (DSG), the SSR engine function will be built into two separate functions:

• A default function for SSR function handler.
• A cached DSG build for pages marked with defer: true.

The default runtime is nodejs20; override it with the functionsRuntime option. The directory is re-created on each build, so do not commit it.

Adapter options

Pass options to the adapter factory in gatsby-config.js:

adapter: firebaseAdapter({
  hostingTarget: 'gatsby',
  functionsOutDir: '.firebase/functions',
  functionsCodebase: 'gatsby',
  functionsRuntime: 'nodejs20',
  functionsConfig: { region: 'us-central1' },
  functionsConfigOverride: { 'ssr-engine': { memory: '512MiB' } },
  storageBucket: 'my-project.appspot.com',
  excludeDatastoreFromEngineFunction: false,
})

hostingTarget

The Firebase Hosting target in firebase.json to replace. Match this with:

firebase --project <project-id> target:apply hosting <target> <site-id>

functionsOutDir

Directory for the generated Firebase Functions workspace.

functionsCodebase

The codebase name used in firebase.json.

functionsRuntime

Runtime string passed to Firebase. Supported runtimes are nodejs20 (default) and nodejs22.

functionsConfig

Default HTTPS options applied to every generated function. See Functions Runtime Options.

functionsConfigOverride

Per-function overrides keyed by Gatsby functionId. Append -cached to target the cached variant (e.g. ssr-engine-cached). See Functions Runtime Options.

storageBucket

Overrides the Firebase Storage bucket used for DSG caching. Leave unset to use the project’s default bucket.

excludeDatastoreFromEngineFunction

When true, the adapter keeps Gatsby’s LMDB datastore out of SSR/DSG bundles. Set DEPLOY_URL env var during the build so the functions can download the datastore on demand; otherwise the option is ignored.

DSG functions

The adapter supports Deferred Static Generation (DSG) by automatically creating a cached build of Gatsby SSR Engine Function. It behaves similarly to Gatsby Cloud but relies on Firebase Storage.

To enable DSG caching, your Firebase project must have Cloud Storage enabled.

Key characteristics

• They accept only GET and HEAD requests.
• They use the default Firebase Storage bucket (unless overridden with storageBucket option) to store caches under .gatsby-adapter-firebase/<functionId>.
• They use the request’s URL path to determine whether to create a new cache object or reuse an existing one.
• On a miss, the underlying Gatsby handler runs. The proxy records outgoing response chunks for GET requests only.
• When the response finishes with status 2xx, 301, 302, 307, 308, or 404, the payload and headers are written to Storage.
• Cached requests return X-Gatsby-Firebase-Cache: HIT. All other statuses skip caching and return MISS.
• If Storage is unreachable for any reason, the request falls back to standard SSR behavior with no caching and returns X-Gatsby-Firebase-Cache: PASS.

The handler always sets cache-control unless the function already provided one:

• Cacheable responses get public, max-age=0, must-revalidate.
• Non-cacheable responses get no-store.
• Unsupported methods respond with 405 Method Not Allowed and cache-control: no-store.

Each cached response carries the function version in its metadata, so older entries become stale automatically after deploying updated code.

Local workflows

Local deployment

Deploying functions from a local machine only works on Linux (or within a Docker container); other operating systems will produce an error like:

Error: Incompatible DSG/SSR executing environment. Function was built for "linux/x64" but is executing on "darwin/x64".

This is because Gatsby bundles platform-specific binaries inside functions—and Firebase CLI evaluates the functions code before deploying it.

Local testing

You can run the project locally using Firebase Local Emulator Suite.

firebase emulators:start --project demo-site

If you are using DSG, you will need Firebase Storage emulator to be enabled in your firebase.json.

{
  "emulators": {
    "storage": {
      "port": 9199
    }
  }
}

Limitations

At the moment, the adapter has limited support for these features:

SSR and DSG (local images/files not working)

If you have a query that pulls in a local image or file into your page component, the adapter will not be able to resolve it during SSR or DSG. This is because the adapter doesn't receive those files during gatsby build as part of Gatsby's functions manifest.

export const query = graphql`
  query {
    avatar: file(relativePath: { eq: "images/avatar.png" }) {
      childImageSharp {
        image: gatsbyImageData(height: 400, placeholder: BLURRED)
      }
    }
  }
`

License

MIT