Gatsby Source Build Date

1.0.1 · active · verified Tue Apr 21

The `gatsby-source-build-date` plugin, currently at version 1.0.1, provides a straightforward mechanism for integrating the site's compilation timestamp into Gatsby's internal GraphQL API. This enables developers to easily display a "Last Updated" or "Last Built" date in any component or page without manual updates. Unlike its predecessor, `gatsby-plugin-build-date`, this hard fork leverages Node.js's native `Intl.DateTimeFormat` for date internationalization and formatting, eliminating the dependency on third-party date libraries. This approach offers robust localization capabilities, allowing developers to specify `locales` and `options` directly in their `gatsby-config.js` for precise date string representation. The plugin makes the build date available as a `buildDate` node in the GraphQL schema, which can then be queried and formatted using Gatsby's standard GraphQL `formatString` arguments for `Date` types. It is specifically designed to reflect the timestamp of the entire site build process, not individual file modification times. As a Gatsby plugin, its release cadence is generally tied to the stability of the core Gatsby ecosystem, with updates typically addressing compatibility or minor enhancements rather than frequent breaking changes, especially given its reliance on a core Node.js API.

Common errors

```
Date formatting and localization not applied as configured
```
cause Running the Gatsby build process with Node.js version 12.x or earlier, which has known issues with `Intl.DateTimeFormat` respecting locale options.

fix Upgrade your Node.js runtime to version 13 or newer. If deploying, check and configure the Node.js version of your CI/CD environment or hosting provider to ensure it's at least 13.

Warnings

gotcha Node.js versions 12.x (e.g., v12.22) may ignore locale strings and formatting options provided to the plugin, resulting in dates being displayed in default English format regardless of configuration.
Fix: Ensure your Node.js environment is version 13 or higher. For deployment platforms like Netlify, explicitly set the Node.js version in your environment variables (e.g., `NODE_VERSION=14`).

Install

npm install gatsby-source-build-date npm
yarn add gatsby-source-build-date yarn
pnpm add gatsby-source-build-date pnpm

Imports

gatsby-source-build-date
wrong:
```
import 'gatsby-source-build-date'; // Incorrect for Gatsby plugins
```
correct:
```
// In gatsby-config.js
module.exports = {
  plugins: [
    `gatsby-source-build-date`
  ],
};
```
Gatsby plugins are configured by their string name in `gatsby-config.js` for default behavior, not directly imported into component files.

gatsby-source-build-date (with options)

wrong:

const pluginConfig = require('gatsby-source-build-date').config; // Incorrect module usage

correct:

// In gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-build-date`,
      options: {
        locales: "fr-FR",
        options: { weekday: "long", year: "numeric", month: "long", day: "numeric" }
      }
    }
  ],
};

To specify localization or formatting, the plugin must be configured as an object in `gatsby-config.js`.

buildDate (GraphQL field)

wrong:

import { buildDate } from 'gatsby-source-build-date'; // This field is part of GraphQL API, not a direct JS export

correct:

query MySiteBuildDate {
  buildDate {
    date(formatString: "MMMM DD, YYYY HH:mm:ss z")
  }
}

The build date is exposed as the `buildDate` field in Gatsby's GraphQL API, accessible via `useStaticQuery` or page queries in components.

Quickstart

Demonstrates how to configure `gatsby-source-build-date` in `gatsby-config.js` with custom options and how to query the build date via GraphQL.

// gatsby-config.ts (or .js)
import type { GatsbyConfig } from 'gatsby';

const config: GatsbyConfig = {
  plugins: [
    {
      resolve: `gatsby-source-build-date`,
      options: {
        locales: "en-US", // or "fr-FR", etc.
        options: {
          year: "numeric",
          month: "long",
          day: "numeric",
          hour: "numeric",
          minute: "numeric",
          second: "numeric",
          timeZoneName: "short",
        },
      },
    },
  ],
};

export default config;

// Example GraphQL query (run in Gatsby's GraphiQL IDE or a page query)
// After configuring, restart your Gatsby development server.
// Then navigate to http://localhost:8000/___graphql and run this query:
/*
query SiteBuildDate {
  buildDate {
    date
    # The date field is a Date object, allowing further formatting with formatString
    formattedDate: date(formatString: "YYYY-MM-DD HH:mm:ss Z")
  }
}
*/

view raw JSON →