vite-plugin-version-mark

August 5, 2025 · View on GitHub

中文 | English

vite-plugin-version-mark

A Vite/Nuxt plugin that automatically injects version information (package.json version, git commit SHA, or custom commands) into your application via console, global variables, meta tags, and static files.

Install

pnpm add -D vite-plugin-version-mark
# OR yarn add -D vite-plugin-version-mark
# OR npm install -D vite-plugin-version-mark

Usage

Vite

// vite.config.ts
import { defineConfig } from "vite";
import { vitePluginVersionMark } from "vite-plugin-version-mark";

export default defineConfig({
  plugins: [
    vitePluginVersionMark({
      // name: 'test-app',
      // version: '0.0.1',
      // command: 'git describe --tags',
      // outputFile: true,
      // ifGitSHA: true,
      ifShortSHA: true,
      ifMeta: true,
      ifLog: true,
      ifGlobal: true,
    }),
  ],
});

Nuxt3+

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    [
      "vite-plugin-version-mark/nuxt",
      {
        // name: 'test-app',
        // version: '0.0.1',
        // command: 'git describe --tags',
        // outputFile: true,
        // ifGitSHA: true,
        ifShortSHA: true,
        ifMeta: true,
        ifLog: true,
        ifGlobal: true,
      },
    ],
  ],
});

Then you can use vite-plugin-version-mark ! 🎉

🚀 What's New in v0.2.0: Multi-command support! Now you can execute multiple git commands and combine their results with custom formats. Perfect for creating version strings like "main-abc1234" or "v1.0.0-main-abc1234". See examples below ⬇️

Config

vite-plugin-version-mark can be print application version in the Console, defined global or add <meta> in HTML element.

Name	Description	Type	Default	Supported
name	application name	`string`	`name` in package.json	`0.0.1+`
version	application version	`string`	`version` in package.json	`0.0.1+`
ifGitSHA	use git commit SHA as the version	`boolean`	false	`0.0.1+`
ifShortSHA	use git commit short SHA as the version	`boolean`	false	`0.0.1+`
command	provide a custom command to retrieve the version New: Now supports multiple commands! For example: `git describe --tags` or `{ commands: ['git branch --show-current', 'git rev-parse --short HEAD'], format: '{0}-{1}' }`	`string` \| `MultiCommandOptions`	git rev-parse --short HEAD	`0.0.8+`
ifLog	print info in the Console	`boolean`	true	`0.0.1+`
ifGlobal	set a variable named `__${APPNAME}_VERSION__` in the window For TypeScript users, make sure to add the type declarations in the env.d.ts or vite-env.d.ts file to get type checks and Intellisense.	`boolean`	true	`0.0.4+`
ifMeta	add <meta name="application-name" content="{APPNAME_VERSION}: {version}"> in the <head>	`boolean`	true	`0.0.1+`
ifExport	export the version field in the entry file. This may be used when you use vite to build a `library mode`. Through `import { {APPNAME}_VERSION } from <your_library_name>`	`boolean`	false	`0.0.11+`
outputFile	The build generates a static file based on the version, as described in the `outputFile` configuration below.	`boolean`/`function`	false	`0.1.1+`

The version field takes precedence: command > ifShortSHA > ifGitSHA > version

Multi-Command Support 🎉 NEW in v0.2.0

Starting from version 0.2.0+, vite-plugin-version-mark supports executing multiple commands and combining their results! This is perfect for creating version strings that include both branch name and commit SHA.

Basic Multi-Command Usage

// vite.config.ts
import { defineConfig } from "vite";
import { vitePluginVersionMark } from "vite-plugin-version-mark";

export default defineConfig({
  plugins: [
    vitePluginVersionMark({
      // Simple multi-command with default separator
      command: {
        commands: [
          "git rev-parse --abbrev-ref HEAD", // Get branch name
          "git rev-parse --short HEAD", // Get short commit SHA
        ],
        // Output: "main-abc1234"
      },
    }),
  ],
});

Advanced Multi-Command Configuration

// vite.config.ts
export default defineConfig({
  plugins: [
    vitePluginVersionMark({
      command: {
        commands: [
          {
            alias: "branch",
            cmd: "git rev-parse --abbrev-ref HEAD",
            fallback: "unknown",
          },
          { alias: "sha", cmd: "git rev-parse --short HEAD", timeout: 5000 },
          {
            alias: "tag",
            cmd: "git describe --tags --abbrev=0",
            fallback: "v0.0.0",
          },
        ],
        format: "{tag}-{branch}-{sha}", // Custom format template
        errorStrategy: "fallback", // Use fallback values on error
        parallel: true, // Execute commands in parallel
        // Output: "v1.0.0-main-abc1234"
      },
    }),
  ],
});

Multi-Command Options

Option	Description	Type	Default
`commands`	Array of commands to execute. Can be strings or command config objects	`(string \| CommandConfig)[]`	-
`format`	Template string with `{alias}` placeholders for formatting results	`string`	-
`separator`	Default separator when no format template is provided	`string`	`"-"`
`errorStrategy`	How to handle command failures: `"strict"`, `"skip"`, or `"fallback"`	`string`	`"skip"`
`parallel`	Whether to execute commands in parallel for better performance	`boolean`	`true`

Error Handling Strategies

strict: Any command failure will throw an error and stop the build
skip: Failed commands are skipped, their results are empty in the output
fallback: Use the fallback value specified in the command config when a command fails

Command Configuration

Each command can be configured with additional options:

interface CommandConfig {
  alias: string; // Alias for referencing in format template
  cmd: string; // The actual command to execute
  fallback?: string; // Fallback value if command fails
  timeout?: number; // Command timeout in milliseconds (default: 10000)
}

`outputFile` Configuration Option

If you want to enable it, you can set it to true, and it will create a file with the path .well-known/version and the content of the current version number in the relative build directory (dist for vite and .output/public for nuxt3).

Alternatively, it can be set to a function that takes the version number as a parameter and returns an object. This allows you to define the content information generated, for example:

// vite.config.ts
vitePluginVersionMark({
  // ...other options

  outputFile: (version) => ({
    path: 'custom/version.json',
    content: `{"version":"${version}"}`,
  })
}),

With this configuration, a file named custom/version.json will be generated, and its content will be {"version":"${current version number}"}.

Other

How to get the version in your vitePlugin?

// vite.config.ts

import { defineConfig } from "vite";
import type { Plugin } from "vite";
import { vitePluginVersionMark } from "vite-plugin-version-mark";

const yourPlugin: () => Plugin = () => ({
  name: "test-plugin",
  config(config) {
    // get version in vitePlugin if you open `ifGlobal`
    console.log(config.define);
  },
});

export default defineConfig({
  plugins: [
    vue(),
    vitePluginVersionMark({
      ifGlobal: true,
    }),
    yourPlugin(),
  ],
});

How to get the branch to which it belongs through `commit SHA`?

Through the git command below, you can list all branches containing the specified commit SHA.

git branch -r --contains <COMMIT_SHA>

Star History

View CHANGELOG