Registry /
web-framework / gatsby-plugin-build-date
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
`gatsby-plugin-build-date` (minimal config)
✓ // In gatsby-config.js
module.exports = {
plugins: [
`gatsby-plugin-build-date`
]
}
✗ import gatsbyPluginBuildDate from 'gatsby-plugin-build-date'; // Not imported directly in user code
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.
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;
*/
Debug
Known issues
gotchaThis 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.fixFor 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.
affects: >=1.0.0
gotchaNode.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`.fixLeverage 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.
affects: >=1.0.0
gotchaWithout 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.fixAlways 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`.
affects: >=1.0.0
gotchaIf `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.fixIf 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.
affects: >=1.0.0
breakingThis 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.fixTest 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.
affects: <=1.0.0 (when used with Gatsby >=3.0.0)
Errors
Common errors & fixes
Cannot query field `currentBuildDate` on type `Query`
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.
fixEnsure `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.
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.
fixReview 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.
Misunderstanding the plugin's intended scope. `gatsby-plugin-build-date` provides a *site-wide* build timestamp, not specific file modification dates.
fixFor 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.
Audit
Dependencies
gatsbyrequiredPeer dependency, required as this is a Gatsby plugin.