{"id":16822,"library":"gatsby-plugin-build-date","title":"Gatsby Plugin Build Date","description":"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.","status":"maintenance","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/garethpbk/gatsby-plugin-build-date","tags":["javascript","gatsby","gatsby-plugin","date","build date","updated date"],"install":[{"cmd":"npm install gatsby-plugin-build-date","lang":"bash","label":"npm"},{"cmd":"yarn add gatsby-plugin-build-date","lang":"bash","label":"yarn"},{"cmd":"pnpm add gatsby-plugin-build-date","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required as this is a Gatsby plugin.","package":"gatsby","optional":false}],"imports":[{"note":"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.","wrong":"import gatsbyPluginBuildDate from 'gatsby-plugin-build-date'; // Not imported directly in user code","symbol":"`gatsby-plugin-build-date` (minimal config)","correct":"// In gatsby-config.js\nmodule.exports = {\n  plugins: [\n    `gatsby-plugin-build-date`\n  ]\n}"},{"note":"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.","symbol":"`gatsby-plugin-build-date` (with options)","correct":"// In gatsby-config.js\nmodule.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-plugin-build-date`,\n      options: {\n        formatAsDateString: true,\n        formatting: {\n          format: 'dddd D MMMM YYYY',\n          utc: false\n        },\n        locale: 'fr'\n      }\n    }\n  ]\n}"},{"note":"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.","symbol":"`currentBuildDate` (GraphQL query)","correct":"query MySiteBuildDate {\n  currentBuildDate {\n    currentDate\n  }\n}"}],"quickstart":{"code":"// In your gatsby-config.js\n\nmodule.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-plugin-build-date`,\n      options: {\n        formatAsDateString: true, // boolean, defaults to true\n        formatting: {\n          format: 'YYYY-MM-DD HH:mm:ss', // ISO-like format with time\n          utc: true // output time as UTC\n        },\n        locale: 'en' // default locale\n      }\n    },\n  ],\n}\n\n// In a Gatsby component (e.g., in a page query or static query):\n// Assuming 'data' prop is available from a page query\n// or 'useStaticQuery' hook\n\n/*\nimport { graphql, useStaticQuery } from 'gatsby';\n\nfunction Footer() {\n  const data = useStaticQuery(graphql`\n    query BuildDateQuery {\n      currentBuildDate {\n        currentDate\n      }\n    }\n  `);\n\n  return (\n    <footer>\n      Last Built: {data.currentBuildDate.currentDate} UTC\n    </footer>\n  );\n}\n\nexport default Footer;\n*/","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<=1.0.0 (when used with Gatsby >=3.0.0)"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`).","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.","error":"Cannot query field `currentBuildDate` on type `Query`"},{"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`.","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.","error":"Date returned from GraphQL is in the wrong format or locale."},{"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.","cause":"Misunderstanding the plugin's intended scope. `gatsby-plugin-build-date` provides a *site-wide* build timestamp, not specific file modification dates.","error":"I want to display when a specific blog post or page was last updated, but `currentBuildDate` shows the site build date."}],"ecosystem":"npm","meta_description":null}