vite-plugin-version-mark
v0.2.2
Published
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.
Maintainers
zhongxuyangReadme
中文 | 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-markUsage
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-markcan be print application version in theConsole, definedglobalor 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 windowFor 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 buildskip: Failed commands are skipped, their results are empty in the outputfallback: Use thefallbackvalue 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