vite-plugin-version-info

A Vite plugin that injects version metadata into your app at build time. Useful for displaying neat version strings and commit timestamps in your UI or console.

npm • Repository • Issues

✨ Features

• Injects version string and commit date from Git and package.json
• Fully customizable version format via pattern tokens
• Locale-aware and timezone-aware commit date and time formatting
• Detects missing license and appends customizable suffix
• Adds branch suffix based on NODE_ENV
• Injects global constants at build time — no runtime overhead or bundle size impact

📦 Installation

Install using your preferred package manager:

npm install -D vite-plugin-version-info
# or
pnpm add -D vite-plugin-version-info

🚀 Usage

Add the plugin to your vite.config.ts or vite.config.js:

import versionInfo from 'vite-plugin-version-info';

export default defineConfig({
  plugins: [
    /* other plugins */
    versionInfo({
      locale: 'en-GB',
      commitHashLength: 8,
      noLicenseSuffix: '-proprietary',
      pattern: '{version}-{commitHash}{noLicenseSuffix}',
    }),
  ],
});

Or, with all options omitted (using defaults):

import versionInfo from 'vite-plugin-version-info';

export default defineConfig({
  plugins: [
    /* other plugins */
    versionInfo(),
  ],
});

If using typescript, define the exposed constants in a separate src/globals.d.ts file:

declare const __APP_VERSION__: string;
declare const __COMMIT_DATE__: string;

Then use the global constants injected by the plugin anywhere in your app:

console.log(`Build version: ${__APP_VERSION__} - committed on ${__COMMIT_DATE__}`);

Example output:

Build version: 1.2.3-4afb2a1e-proprietary - committed on July 7, 2025

Or, using defaults:

1.2.3-nonfree develop-4afb2a1e - commited on July 7, 2025

🧪 Injected Globals

These globals are injected at build time and can be accessed anywhere in your UI code or logic.

| Global | Type | Description | | ----------------- | -------- | --------------------------------------- | | __APP_VERSION__ | string | Fully formatted version string | | __COMMIT_DATE__ | string | Formatted date of the latest Git commit |

🛠️ Options

| Option | Type | Default | Description | | ------------------ | ---------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------- | | locale | string | 'en-US' | Locale used to format the commit date | | commitHashLength | number | 8 | Number of characters to use from the Git commit hash | | intlOptions | Intl.DateTimeFormatOptions | { dateStyle: 'long' } | Intl.DateTimeFormat options to customize commit date formatting | | noLicenseSuffix | string | '-nonfree' | Suffix appended to version string if no license is found | | pattern | string | '{version}{noLicenseSuffix} {currentBranch}-{commitHash}{branchSuffix}' | Template string to format the final version string |

🧩 Pattern Tokens

You can customize the versionString using a template string with the following tokens. These will be replaced at build time:

| Token | Description | Example | | ------------------- | ----------------------------------------------- | -------------------------------------- | | {version} | Version from your package.json | 1.2.3 | | {noLicenseSuffix} | Appended if license field is missing | -nonfree, -unlicensed, or empty | | {currentBranch} | Current Git branch name | main, develop, feature/login-fix | | {commitHash} | Git commit hash truncated to commitHashLength | 4afb2a1e | | {branchSuffix} | -dev if NODE_ENV starts with "dev" | -dev or empty |

🔧 Example Output

Given the following plugin options:

{
  pattern: '{version}{noLicenseSuffix}-{currentBranch}-{commitHash}{branchSuffix}',
  commitHashLength: 8,
}

And your environment:

• version field in package.json is 1.2.3
• license field missing in package.json
• Current git branch is develop
• Last commit hash is 4afb2a1efddc3a34... → shortened to 4afb2a1e
• NODE_ENV=development

Then the result will be:

versionString = '1.2.3-nonfree-develop-4afb2a1e-dev';

You can fully control the format by editing the pattern string.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT