stamper library

Build-time stamping for Flutter web output (uses dart:io; import it from scripts and tools, not from app code).

import 'package:web_update_guard/stamper.dart';

final result = stampBuildDirectory('build/web');
print(result.info.buildId);

Classes

BuildInfo

Metadata about one deployed build, as written to version.json by the stamp CLI.

StampResult

The outcome of stampBuildDirectory.

Constants

buildIdMetaName → const String

The name of the <meta> tag the stamp CLI injects into index.html.

cacheBustedScripts → const List<String>

Entry-point file names whose references the stamp CLI cache-busts: the dart2js bundle, the loader scripts and the dart2wasm module + its JS support runtime.

Functions

buildTimeFromId(String buildId) → DateTime?

Extracts the UTC build time embedded in a build ID made by formatBuildId, or null when buildId has another format.

cacheBustScripts(String source, String buildId) → String

Appends ?v=<buildId> to every script reference in source, replacing a previous v parameter and keeping any other parameters.

formatBuildId(String contentHash, DateTime builtAt) → String

Formats a build ID from a hex contentHash and the build time.

injectBuildIdMeta(String html, String buildId) → String

Inserts the build-ID meta tag just before </head>, removing any previous one first.

removeBuildIdMeta(String html) → String

Removes every build-ID meta tag (and its line) from html.

removeCacheBust(String source) → String

Removes the v parameter added by cacheBustScripts.

runCli(List<String> arguments, {StringSink? out, StringSink? err}) → int

Runs the web_update_guard command line with arguments, writing to out and err (stdout/stderr by default), and returns the exit code: 0 success, 64 usage error, 1 stamping failure.

stampBootstrapJs(String js, String buildId) → String

Returns js (a flutter_bootstrap.js) with script references cache-busted with buildId. Idempotent.

stampBuildDirectory(String buildDir, {String? pubspecPath, String? appVersion, bool force = false, DateTime? now}) → StampResult

Stamps a flutter build web output directory in place.

stampIndexHtml(String html, String buildId) → String

Returns html (an index.html) stamped with buildId: meta tag injected and script references outside HTML comments cache-busted. Idempotent.

unstampIndexHtml(String html) → String

Returns html (an index.html) with the meta tag and cache-busting removed — the form used for content hashing.

Exceptions / Errors

StampException

Thrown when a build directory cannot be stamped.