Astro Integration
Astro Build ID
Identify exactly which build is deployed using a single static file — deterministic, cache-safe, and explicit.
Last Updated: 01 April 2026
Usage Snapshot
26
Downloads in Last 30 Days
v1.0.1
Latest npm Version
Source: npm registry
Why This Plugin Exists
With static sites and CDNs, it is often unclear whether a deployment actually updated or which build is currently live.
astro-build-id solves this by writing a single immutable identifier file during astro build.
The output is static, public-safe, and works behind any CDN without runtime logic or environment inference.
Design Principles
- Build-time only, zero runtime logic
- Single immutable source of truth
- Deterministic and cache-safe output
- Explicit configuration over guessing
- Never blocks a deployment
What This Plugin Delivers
- Writes a single static build identifier file
- Supports ISO, Unix, and short deterministic formats
- Allows custom filenames
- Supports explicit CI-provided values
- Works behind any CDN or static host
- Zero runtime JavaScript
Installation
npm install astro-build-id
The plugin runs during astro build and writes a static build identifier file to the final output directory.
FAQs
What does Astro Build ID do?
Astro Build ID writes a single static file containing an immutable identifier representing the build that was deployed.
Does Astro Build ID run at runtime?
No. The plugin runs exclusively at build time and produces static output.
Can I provide my own build ID?
Yes. You can pass an explicit value, such as a CI build number, which will be written verbatim.
Implementation FAQs
Why does Astro Build ID exist?
To provide a simple, reliable way to identify which build is currently deployed, especially on static sites behind CDNs.
What build ID formats are supported?
ISO timestamps (default), Unix timestamps, and a short deterministic identifier.
Can I change the output filename?
Yes. You can configure a custom filename, such as health.txt or version.txt.
Can I use a CI-provided value?
Yes. If a value is provided explicitly, it is written verbatim and overrides any format.
Is the output cache-safe?
Yes. The output is static and can be cached indefinitely by CDNs.
What happens if the file cannot be written?
A warning is logged, the build continues, and the site is not broken.
Project Links
Source code, package distribution, releases, and documentation.
Need Implementation Details?
Read the FAQs for usage patterns, integration caveats, and rollout guidance.