buildwatch

Generate Vite build version metadata and watch it from the browser so an app can react when a new build is deployed.

What it does

• Adds a Vite build plugin that writes a version.json file based on the generated manifest.
• Exposes a small browser watcher that fetches that file when the page becomes visible.
• Calls your callback when the deployed build version changes.

Requirements

• Node 24+
• Vite 5+

Installation

npm install buildwatch

Vite setup

Enable Vite's manifest output and add the plugin:

// vite.config.js
import { defineConfig } from "vite";
import { versionJsonPlugin } from "buildwatch/version-json-plugin";

export default defineConfig({
  build: {
    manifest: true,
  },
  plugins: [versionJsonPlugin()],
});

By default, the plugin reads manifest.json from Vite's output directory and writes version.json beside it.

Browser usage

import watchVersion from "buildwatch";

const stopWatching = watchVersion((newVersion, oldVersion) => {
  console.log(`New build available: ${oldVersion} -> ${newVersion}`);

  // Common options: show a refresh prompt, reload the page, or notify the user.
});

// Later, if needed:
stopWatching();

The watcher checks /build/version.json by default. It performs an initial fetch immediately, then checks again when the document becomes visible. Checks are throttled to once per minute by default.

Options

versionJsonPlugin(options)

versionJsonPlugin({
  algorithm: "sha256",
  fileName: "version.json",
  manifestPath: "dist/.vite/manifest.json",
  outputPath: "dist/build/version.json",
});

• algorithm: hash algorithm passed to Node's createHash; defaults to sha256.
• fileName: output filename when outputPath is not set; defaults to version.json.
• manifestPath: path to the Vite manifest, relative to the Vite root.
• outputPath: explicit output path, relative to the Vite root.

watchVersion(onChange, options)

watchVersion(onChange, {
  minCheckInterval: 30_000,
  url: "/build/version.json",
});

• minCheckInterval: minimum time between fetches in milliseconds; defaults to 60000.
• url: URL for the generated version JSON; defaults to /build/version.json.

Development

npm install
npm test
npm run lint

npm run prepack runs both linting and tests.