Gatsby Plugin Build Date

1.0.0 · maintenance · verified Wed Apr 22

This Gatsby plugin, currently at version 1.0.0, provides a utility for injecting the site's build timestamp into the internal GraphQL API under the `currentBuildDate` type. It is designed to make the site's last build date accessible within components and pages, useful for displaying 'Last Updated' footers. The date is generated statically at build time, ensuring consistency across deployments. A key differentiator is its integration with the `date-and-time` library for robust date formatting and localization, which circumvents Node.js's default `toLocaleString()` limitations that typically only support 'en-US'. The plugin's release cadence is generally slow for a utility of this nature, with releases primarily focusing on stability or compatibility with new Gatsby major versions, rather than frequent feature additions. It explicitly clarifies that it's for the overall site build date, not individual file modification times.

Common errors

```
Cannot query field `currentBuildDate` on type `Query`
```
cause The plugin `gatsby-plugin-build-date` has not been correctly included in `gatsby-config.js`, or the Gatsby development server has not been restarted after configuration changes.

fix Ensure `gatsby-plugin-build-date` is listed in the `plugins` array in `gatsby-config.js` (either as a string or an object with `resolve`). Then, restart your Gatsby development server (`gatsby develop`) or rebuild your site (`gatsby build`).
```
Date returned from GraphQL is in the wrong format or locale.
```
cause Incorrect or missing `formatting` and `locale` options in `gatsby-config.js` for the plugin, or `formatAsDateString` is set to `false`, returning an unformatted ISO string.

fix Review the `options` object for `gatsby-plugin-build-date` in `gatsby-config.js`. Ensure `formatAsDateString: true` and correctly configure `formatting.format` (e.g., 'DD/MM/YYYY') and `locale` (e.g., 'es') according to the `date-and-time` library documentation. Remember to rebuild or restart `gatsby develop`.
```
I want to display when a specific blog post or page was last updated, but `currentBuildDate` shows the site build date.
```
cause Misunderstanding the plugin's intended scope. `gatsby-plugin-build-date` provides a *site-wide* build timestamp, not specific file modification dates.

fix For file-specific last modified dates, consider using other Gatsby plugins that integrate with your data source (e.g., `gatsby-source-filesystem` with `gatsby-transformer-remark` that can read frontmatter `date` fields, or a headless CMS that provides update timestamps). This plugin is not suitable for individual content updates.

Warnings

gotcha This plugin is designed to provide the *site's overall build timestamp*, not the last modified date of individual files (e.g., blog posts or images). Developers often misinterpret its scope.
Fix: For file-specific modification dates, use alternative Gatsby plugins that leverage file system metadata or integrate with CMS APIs. Do not attempt to use `gatsby-plugin-build-date` for this purpose.
gotcha Node.js environments often have limited locale data, defaulting `toLocaleString()` to 'en-US'. This plugin uses the `date-and-time` library to offer robust formatting and localization, so developers should use the plugin's `formatting` and `locale` options instead of client-side `toLocaleString` unless `formatAsDateString` is explicitly set to `false`.
Fix: Leverage the `formatting.format` and `locale` options within `gatsby-config.js` for consistent date output. Only set `formatAsDateString: false` if client-side formatting with a more comprehensive locale library is intended.
gotcha Without explicit `formatting` options, the date will default to 'MM/DD/YYYY' (e.g., '12/20/2019'). This might not be suitable for all international users or regional date formats.
Fix: Always specify `formatting.format` in your `gatsby-config.js` to match your desired date display, such as 'DD/MM/YYYY' or 'YYYY-MM-DD', along with an appropriate `locale`.
gotcha If `formatAsDateString` is set to `false`, the GraphQL API will return an unformatted ISO string from `new Date()` (e.g., `2019-12-20T18:16:57.374Z`). This requires client-side parsing and formatting, which can be unexpected if a pre-formatted string was anticipated.
Fix: If you want the plugin to handle formatting, ensure `formatAsDateString` is `true` (its default) and configure the `formatting` and `locale` options. If `false`, be prepared to parse and format the `currentDate` string in your React components.
breaking This plugin explicitly targets Gatsby `^2.0.0` as a peer dependency. While it may function with newer major versions of Gatsby (v3, v4, v5+), compatibility is not guaranteed, and potential breaking changes in Gatsby's core APIs might affect its operation.
Fix: Test thoroughly when using with Gatsby versions higher than 2.x. Check the plugin's GitHub repository for any updates or compatibility notes regarding newer Gatsby releases. If issues arise, consider creating an issue or migrating to a more actively maintained alternative if one exists.

Install

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

Imports

`gatsby-plugin-build-date` (minimal config)
wrong:
```
import gatsbyPluginBuildDate from 'gatsby-plugin-build-date'; // Not imported directly in user code
```
correct:
```
// In gatsby-config.js
module.exports = {
  plugins: [
    `gatsby-plugin-build-date`
  ]
}
```
Gatsby plugins are configured as strings or objects within the `plugins` array in `gatsby-config.js`, which is a CommonJS module. They are not directly imported into user components.

`gatsby-plugin-build-date` (with options)

// In gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-build-date`,
      options: {
        formatAsDateString: true,
        formatting: {
          format: 'dddd D MMMM YYYY',
          utc: false
        },
        locale: 'fr'
      }
    }
  ]
}

When custom formatting or localization is required, the plugin is configured as an object with a `resolve` property pointing to the plugin name and an `options` object.

`currentBuildDate` (GraphQL query)
```
query MySiteBuildDate {
  currentBuildDate {
    currentDate
  }
}
```
The build date is exposed via Gatsby's internal GraphQL API under the `currentBuildDate` type, accessible through the `currentDate` field. This is how the data is 'imported' into components.

Quickstart

Demonstrates how to configure the plugin in `gatsby-config.js` with options for custom date formatting and provides a commented example of how to query and display the build date in a React component.

// In your gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-build-date`,
      options: {
        formatAsDateString: true, // boolean, defaults to true
        formatting: {
          format: 'YYYY-MM-DD HH:mm:ss', // ISO-like format with time
          utc: true // output time as UTC
        },
        locale: 'en' // default locale
      }
    },
  ],
}

// In a Gatsby component (e.g., in a page query or static query):
// Assuming 'data' prop is available from a page query
// or 'useStaticQuery' hook

/*
import { graphql, useStaticQuery } from 'gatsby';

function Footer() {
  const data = useStaticQuery(graphql`
    query BuildDateQuery {
      currentBuildDate {
        currentDate
      }
    }
  `);

  return (
    <footer>
      Last Built: {data.currentBuildDate.currentDate} UTC
    </footer>
  );
}

export default Footer;
*/

view raw JSON →