@game-infra/build-utils

Build-time git metadata injection for Vite builds, plus runtime access to it. At build time, @game-infra/build-utils/git-info reads the current revision, branch, commit message, and dirty state and turns them into Vite define constants. At runtime, the BuildInfo class reads those constants back, with safe fallbacks when they were never injected. The package also ships ServiceConfig, a small process-wide holder for the backend API config a game talks to.

Linking

This package is consumed as a sibling source checkout, not from npm (see docs/CONSUMING.md).

// pnpm consumer
{ "dependencies": { "@game-infra/build-utils": "link:../../../game-infra/packages/build-utils" } }

// npm consumer
{ "dependencies": { "@game-infra/build-utils": "file:../../../game-infra/packages/build-utils" } }

Usage

Inject git info in a Vite config (./git-info subpath)

// vite.config.ts
import { defineConfig } from "vite";
import { getGitInfo, getGitDefines, formatGitVersion } from "@game-infra/build-utils/git-info";

const gitInfo = getGitInfo();
console.log(`Building ${formatGitVersion(gitInfo)}`);

export default defineConfig({
  define: getGitDefines(gitInfo, "production"),
});

getGitDefines produces the full __GIT_*__ / __BUILD_*__ constant map. If git is unavailable, getGitInfo returns fallback values instead of failing the build.

Read build info at runtime

import { BuildInfo } from "@game-infra/build-utils";

BuildInfo.getVersion(); // "2bdf112 (main)"
BuildInfo.getDetailedVersion(); // "2bdf112 (main) - Built: 2025-01-15T10:30:00Z [production]"
BuildInfo.getRevision(); // "2bdf112" or "2bdf112-dirty"
BuildInfo.isDirty(); // true when built from an unclean working tree
BuildInfo.logInfo(); // dump everything to the console

Any accessor returns "unknown" (or the current time / false) when the constants were not injected, so the same code runs in dev servers and tests.

Configure backend services at startup

import { BuildInfo, ServiceConfig } from "@game-infra/build-utils";

ServiceConfig.initialize(
  ServiceConfig.createAutoConfig("my-game", BuildInfo.getVersion(), "https://api.example.com"),
);

// anywhere later:
const { apiBaseUrl, gameId, gameVersion } = ServiceConfig.get();

createAutoConfig picks a http://localhost:8787 dev config when the page is served from localhost (matching wrangler dev's default port) and the production config otherwise.

Exports

• . (TypeScript source): BuildInfo, ServiceConfig, GameServiceConfig
• ./git-info (plain .mjs, importable from Vite configs before any TS tooling runs): getGitInfo, formatGitVersion, getGitDefines, GitInfo (type)

Internal deps

None. Runtime deps: none (node builtins only at build time).

Consumers

Game repos that display a build version in the UI or report it to backend services, and their Vite configs.