vite-plugin-build-version-file 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,362 @@
+# vite-plugin-build-version
+
+一个面向 `Vue 3 + Vite` 的构建版本插件。
+
+它会在项目运行和构建时提供统一的版本信息：
+
+- 构建产物中生成 `version.json`
+- 可选地向 HTML 注入 `window["__VERSION__"]`
+- 支持自定义版本号、文件名和全局变量名
+
+适合用在这些场景：
+
+- 页面显示当前前端版本
+- 检测线上是否有新版本并提示刷新
+- 灰度发布时对比本地版本和服务端版本
+
+## 适用范围
+
+- 仅支持 `Vite`
+- 主要面向 `Vue 3` 项目使用
+- `peerDependencies` 要求 `vite >= 5`
+- 运行环境要求 `node >= 18`
+
+## 安装
+
+```bash
+pnpm add vite-plugin-build-version
+```
+
+也可以使用：
+
+```bash
+npm install vite-plugin-build-version
+```
+
+## 快速开始
+
+```ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import buildVersionPlugin from 'vite-plugin-build-version'
+
+export default defineConfig({
+  plugins: [vue(), buildVersionPlugin()]
+})
+```
+
+## 默认行为
+
+在默认配置下，插件会执行以下行为：
+
+- 开发态访问 `/version.json` 时返回版本信息
+- 构建后在输出目录生成 `version.json`
+- 构建后的 HTML 中注入 `window["__VERSION__"]`
+- 开发态默认版本号为 `0`
+- 构建态默认版本号为当前时间戳，格式为 `YYYYMMDDHHmmss`
+
+默认生成的版本文件内容如下：
+
+```json
+{
+  "version": "20260401153045",
+  "production": true
+}
+```
+
+开发态默认返回：
+
+```json
+{
+  "version": 0,
+  "production": false
+}
+```
+
+## 配置项
+
+```ts
+type BuildVersionContext = {
+  command: 'serve' | 'build'
+  mode: string
+}
+
+type BuildVersionPluginOptions = {
+  filename?: string
+  globalName?: string
+  injectToHtml?: boolean
+  version?: string | number | ((ctx: BuildVersionContext) => string | number)
+}
+```
+
+### `filename`
+
+- 类型：`string`
+- 默认值：`"version.json"`
+- 作用：控制输出文件名
+
+说明：
+
+- 支持相对路径，例如 `meta/version.json`
+- 构建时会输出到 `dist/meta/version.json`
+- 开发态访问路径也会同步变成对应地址
+
+### `globalName`
+
+- 类型：`string`
+- 默认值：`"__VERSION__"`
+- 作用：控制注入到 `window` 上的属性名
+
+默认注入效果：
+
+```html
+<script>
+  window["__VERSION__"] = "20260401153045";
+</script>
+```
+
+### `injectToHtml`
+
+- 类型：`boolean`
+- 默认值：`true`
+- 作用：是否向 HTML 注入 `window` 全局变量
+
+当设置为 `false` 时：
+
+- 仍然会生成 `version.json`
+- 不会注入 `window["__VERSION__"]`
+
+### `version`
+
+- 类型：`string | number | ((ctx) => string | number)`
+- 默认值：开发态为 `0`，构建态为当前时间戳
+- 作用：自定义版本号生成逻辑
+
+如果传入函数，函数会收到：
+
+```ts
+{
+  command: 'serve' | 'build',
+  mode: string
+}
+```
+
+## 使用示例
+
+### 1. 使用默认配置
+
+```ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import buildVersionPlugin from 'vite-plugin-build-version'
+
+export default defineConfig({
+  plugins: [vue(), buildVersionPlugin()]
+})
+```
+
+### 2. 自定义全局变量名
+
+```ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import buildVersionPlugin from 'vite-plugin-build-version'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    buildVersionPlugin({
+      globalName: '__APP_VERSION__'
+    })
+  ]
+})
+```
+
+注入后可以这样读取：
+
+```ts
+const version = window['__APP_VERSION__']
+```
+
+### 3. 只保留 `version.json`，不注入 `window`
+
+```ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import buildVersionPlugin from 'vite-plugin-build-version'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    buildVersionPlugin({
+      injectToHtml: false
+    })
+  ]
+})
+```
+
+### 4. 自定义输出路径
+
+```ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import buildVersionPlugin from 'vite-plugin-build-version'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    buildVersionPlugin({
+      filename: 'meta/version.json'
+    })
+  ]
+})
+```
+
+构建后输出：
+
+```text
+dist/meta/version.json
+```
+
+### 5. 自定义版本号生成逻辑
+
+```ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import buildVersionPlugin from 'vite-plugin-build-version'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    buildVersionPlugin({
+      version: ({ command, mode }) => {
+        if (command === 'serve') {
+          return 0
+        }
+
+        return `${mode}-20260401153045`
+      }
+    })
+  ]
+})
+```
+
+## 在项目中读取版本
+
+### 读取注入的全局变量
+
+```ts
+const version = window['__VERSION__']
+```
+
+### 读取 `version.json`
+
+```ts
+const response = await fetch('/version.json')
+const payload = await response.json()
+
+console.log(payload.version)
+console.log(payload.production)
+```
+
+如果你配置了自定义 `filename`，这里的请求路径也需要改成对应地址。
+
+## 开发态行为说明
+
+开发态下，插件不会往项目的 `public/` 目录写文件。
+
+它会直接通过 Vite dev server 返回版本 JSON，因此：
+
+- 不会污染业务项目目录
+- 更适合本地调试
+- 修改配置后重新启动 dev server 即可看到结果
+
+如果项目配置了 `base`，版本文件访问路径会自动跟随 `base`。
+
+## 本地开发与联调
+
+仓库中已经提供了一个专门用于调试的 `Vite + Vue 3` 测试项目：
+
+- 路径：`debug/fixture-app`
+- 引用方式：直接引用根目录 `dist/index.mjs`
+
+这意味着它测试的是“打包后的真实产物”，而不是源码直连。
+
+### 安装依赖
+
+```bash
+pnpm install
+```
+
+### 构建插件
+
+```bash
+pnpm build
+```
+
+### 启动测试项目
+
+```bash
+pnpm dev:fixture
+```
+
+启动后可以在页面里直接看到：
+
+- `window["__VERSION__"]`
+- `/version.json` 的返回结果
+
+### 构建测试项目
+
+```bash
+pnpm build:fixture
+```
+
+这个命令会先构建插件，再构建测试项目，用来验证 `dist` 产物能否被正常消费。
+
+## 发布到 npm
+
+### 1. 登录 npm
+
+```bash
+npm login
+```
+
+### 2. 构建并验证
+
+```bash
+pnpm build
+pnpm build:fixture
+```
+
+### 3. 发布公开包
+
+```bash
+npm publish --access public
+```
+
+## 发布前检查建议
+
+发布前建议至少确认以下几点：
+
+- `dist/index.mjs`、`dist/index.cjs`、`dist/index.d.ts` 已生成
+- `debug/fixture-app` 可以正常运行或构建
+- `version.json` 输出正常
+- HTML 注入结果符合预期
+- `package.json` 中的 `name`、`version`、`exports`、`publishConfig` 正确
+
+如果你要进一步检查最终发布内容，可以执行：
+
+```bash
+npm pack
+```
+
+正常情况下，发布包中应只包含：
+
+- `dist`
+- `README.md`
+- `LICENSE`
+- `package.json`
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,164 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  buildVersionPlugin: () => buildVersionPlugin,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var PLUGIN_NAME = "vite-plugin-build-version";
+var DEFAULT_FILENAME = "version.json";
+var DEFAULT_GLOBAL_NAME = "__VERSION__";
+function formatBuildTimestamp(date) {
+  const pad = (value) => value.toString().padStart(2, "0");
+  return [
+    date.getFullYear(),
+    pad(date.getMonth() + 1),
+    pad(date.getDate()),
+    pad(date.getHours()),
+    pad(date.getMinutes()),
+    pad(date.getSeconds())
+  ].join("");
+}
+function createDefaultVersion(command) {
+  if (command === "serve") {
+    return 0;
+  }
+  return formatBuildTimestamp(/* @__PURE__ */ new Date());
+}
+function normalizeFileName(filename) {
+  const normalized = filename.replace(/\\/g, "/").replace(/^\/+/, "");
+  if (!normalized || normalized.endsWith("/")) {
+    throw new Error(`[${PLUGIN_NAME}] "filename" must point to a file path.`);
+  }
+  return normalized;
+}
+function normalizeGlobalName(globalName) {
+  if (!globalName.trim()) {
+    throw new Error(`[${PLUGIN_NAME}] "globalName" cannot be empty.`);
+  }
+  return globalName;
+}
+function ensureVersionValue(value) {
+  if (typeof value === "string" || typeof value === "number") {
+    return value;
+  }
+  throw new Error(
+    `[${PLUGIN_NAME}] "version" must resolve to a string or number.`
+  );
+}
+function resolveVersionValue(versionOption, context) {
+  if (versionOption === void 0) {
+    return createDefaultVersion(context.command);
+  }
+  if (typeof versionOption !== "function") {
+    return ensureVersionValue(versionOption);
+  }
+  try {
+    return ensureVersionValue(versionOption(context));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`[${PLUGIN_NAME}] Failed to resolve version: ${message}`);
+  }
+}
+function serializePayload(payload) {
+  return `${JSON.stringify(payload, null, 2)}
+`;
+}
+function parsePathname(requestUrl) {
+  if (!requestUrl) {
+    return "/";
+  }
+  return new URL(requestUrl, "http://localhost").pathname;
+}
+function toRequestPath(base, fileName) {
+  const normalizedBase = base === "./" ? "/" : base || "/";
+  const withLeadingSlash = normalizedBase.startsWith("/") ? normalizedBase : `/${normalizedBase}`;
+  const baseWithoutTrailingSlash = withLeadingSlash.endsWith("/") ? withLeadingSlash.slice(0, -1) : withLeadingSlash;
+  return `${baseWithoutTrailingSlash}/${fileName}`.replace(/\/{2,}/g, "/");
+}
+function buildVersionPlugin(options = {}) {
+  const fileName = normalizeFileName(options.filename ?? DEFAULT_FILENAME);
+  const globalName = normalizeGlobalName(
+    options.globalName ?? DEFAULT_GLOBAL_NAME
+  );
+  const injectToHtml = options.injectToHtml ?? true;
+  let payload;
+  return {
+    name: PLUGIN_NAME,
+    configResolved(config) {
+      const context = {
+        command: config.command,
+        mode: config.mode
+      };
+      payload = {
+        version: resolveVersionValue(options.version, context),
+        production: config.command === "build"
+      };
+    },
+    configureServer(server) {
+      const requestPath = toRequestPath(server.config.base, fileName);
+      server.middlewares.use((request, response, next) => {
+        if (request.method !== "GET" && request.method !== "HEAD") {
+          next();
+          return;
+        }
+        if (parsePathname(request.url) !== requestPath || !payload) {
+          next();
+          return;
+        }
+        const source = serializePayload(payload);
+        response.statusCode = 200;
+        response.setHeader("Content-Type", "application/json; charset=utf-8");
+        response.setHeader("Cache-Control", "no-cache");
+        response.end(request.method === "HEAD" ? void 0 : source);
+      });
+    },
+    transformIndexHtml() {
+      if (!injectToHtml || !payload) {
+        return void 0;
+      }
+      const tags = [
+        {
+          tag: "script",
+          injectTo: "head",
+          children: `window[${JSON.stringify(globalName)}] = ${JSON.stringify(payload.version)};`
+        }
+      ];
+      return tags;
+    },
+    generateBundle() {
+      if (!payload) {
+        return;
+      }
+      this.emitFile({
+        type: "asset",
+        fileName,
+        source: serializePayload(payload)
+      });
+    }
+  };
+}
+var index_default = buildVersionPlugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildVersionPlugin
+});

package/dist/index.d.cts

@@ -0,0 +1,19 @@
+import { Plugin } from 'vite';
+
+interface BuildVersionContext {
+    command: 'serve' | 'build';
+    mode: string;
+}
+interface BuildVersionPayload {
+    version: string | number;
+    production: boolean;
+}
+interface BuildVersionPluginOptions {
+    filename?: string;
+    globalName?: string;
+    injectToHtml?: boolean;
+    version?: string | number | ((ctx: BuildVersionContext) => string | number);
+}
+declare function buildVersionPlugin(options?: BuildVersionPluginOptions): Plugin;
+
+export { type BuildVersionContext, type BuildVersionPayload, type BuildVersionPluginOptions, buildVersionPlugin, buildVersionPlugin as default };

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { Plugin } from 'vite';
+
+interface BuildVersionContext {
+    command: 'serve' | 'build';
+    mode: string;
+}
+interface BuildVersionPayload {
+    version: string | number;
+    production: boolean;
+}
+interface BuildVersionPluginOptions {
+    filename?: string;
+    globalName?: string;
+    injectToHtml?: boolean;
+    version?: string | number | ((ctx: BuildVersionContext) => string | number);
+}
+declare function buildVersionPlugin(options?: BuildVersionPluginOptions): Plugin;
+
+export { type BuildVersionContext, type BuildVersionPayload, type BuildVersionPluginOptions, buildVersionPlugin, buildVersionPlugin as default };

package/dist/index.mjs

@@ -0,0 +1,139 @@
+// src/index.ts
+var PLUGIN_NAME = "vite-plugin-build-version";
+var DEFAULT_FILENAME = "version.json";
+var DEFAULT_GLOBAL_NAME = "__VERSION__";
+function formatBuildTimestamp(date) {
+  const pad = (value) => value.toString().padStart(2, "0");
+  return [
+    date.getFullYear(),
+    pad(date.getMonth() + 1),
+    pad(date.getDate()),
+    pad(date.getHours()),
+    pad(date.getMinutes()),
+    pad(date.getSeconds())
+  ].join("");
+}
+function createDefaultVersion(command) {
+  if (command === "serve") {
+    return 0;
+  }
+  return formatBuildTimestamp(/* @__PURE__ */ new Date());
+}
+function normalizeFileName(filename) {
+  const normalized = filename.replace(/\\/g, "/").replace(/^\/+/, "");
+  if (!normalized || normalized.endsWith("/")) {
+    throw new Error(`[${PLUGIN_NAME}] "filename" must point to a file path.`);
+  }
+  return normalized;
+}
+function normalizeGlobalName(globalName) {
+  if (!globalName.trim()) {
+    throw new Error(`[${PLUGIN_NAME}] "globalName" cannot be empty.`);
+  }
+  return globalName;
+}
+function ensureVersionValue(value) {
+  if (typeof value === "string" || typeof value === "number") {
+    return value;
+  }
+  throw new Error(
+    `[${PLUGIN_NAME}] "version" must resolve to a string or number.`
+  );
+}
+function resolveVersionValue(versionOption, context) {
+  if (versionOption === void 0) {
+    return createDefaultVersion(context.command);
+  }
+  if (typeof versionOption !== "function") {
+    return ensureVersionValue(versionOption);
+  }
+  try {
+    return ensureVersionValue(versionOption(context));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`[${PLUGIN_NAME}] Failed to resolve version: ${message}`);
+  }
+}
+function serializePayload(payload) {
+  return `${JSON.stringify(payload, null, 2)}
+`;
+}
+function parsePathname(requestUrl) {
+  if (!requestUrl) {
+    return "/";
+  }
+  return new URL(requestUrl, "http://localhost").pathname;
+}
+function toRequestPath(base, fileName) {
+  const normalizedBase = base === "./" ? "/" : base || "/";
+  const withLeadingSlash = normalizedBase.startsWith("/") ? normalizedBase : `/${normalizedBase}`;
+  const baseWithoutTrailingSlash = withLeadingSlash.endsWith("/") ? withLeadingSlash.slice(0, -1) : withLeadingSlash;
+  return `${baseWithoutTrailingSlash}/${fileName}`.replace(/\/{2,}/g, "/");
+}
+function buildVersionPlugin(options = {}) {
+  const fileName = normalizeFileName(options.filename ?? DEFAULT_FILENAME);
+  const globalName = normalizeGlobalName(
+    options.globalName ?? DEFAULT_GLOBAL_NAME
+  );
+  const injectToHtml = options.injectToHtml ?? true;
+  let payload;
+  return {
+    name: PLUGIN_NAME,
+    configResolved(config) {
+      const context = {
+        command: config.command,
+        mode: config.mode
+      };
+      payload = {
+        version: resolveVersionValue(options.version, context),
+        production: config.command === "build"
+      };
+    },
+    configureServer(server) {
+      const requestPath = toRequestPath(server.config.base, fileName);
+      server.middlewares.use((request, response, next) => {
+        if (request.method !== "GET" && request.method !== "HEAD") {
+          next();
+          return;
+        }
+        if (parsePathname(request.url) !== requestPath || !payload) {
+          next();
+          return;
+        }
+        const source = serializePayload(payload);
+        response.statusCode = 200;
+        response.setHeader("Content-Type", "application/json; charset=utf-8");
+        response.setHeader("Cache-Control", "no-cache");
+        response.end(request.method === "HEAD" ? void 0 : source);
+      });
+    },
+    transformIndexHtml() {
+      if (!injectToHtml || !payload) {
+        return void 0;
+      }
+      const tags = [
+        {
+          tag: "script",
+          injectTo: "head",
+          children: `window[${JSON.stringify(globalName)}] = ${JSON.stringify(payload.version)};`
+        }
+      ];
+      return tags;
+    },
+    generateBundle() {
+      if (!payload) {
+        return;
+      }
+      this.emitFile({
+        type: "asset",
+        fileName,
+        source: serializePayload(payload)
+      });
+    }
+  };
+}
+var index_default = buildVersionPlugin;
+export {
+  buildVersionPlugin,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "vite-plugin-build-version-file",
+  "version": "0.1.0",
+  "description": "A Vite plugin that emits version.json and injects version metadata into HTML.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "build:fixture": "pnpm build && vite build --config debug/fixture-app/vite.config.ts",
+    "dev:fixture": "pnpm build && vite --config debug/fixture-app/vite.config.ts",
+    "prepublishOnly": "pnpm build:fixture"
+  },
+  "keywords": [
+    "vite",
+    "vite-plugin",
+    "vue3",
+    "build-version",
+    "version-json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@8.15.9",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitejs/plugin-vue": "^5.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0",
+    "vue": "^3.4.0"
+  }
+}