vite-plugin-version-mark

中文 | 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.

Example

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.

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

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