Build Version Tracker

0.0.4 verified Sat Apr 25 auth: no javascript

A universal build tool plugin for automatic version tracking and build automation, supporting Webpack (3.0+) and Vite. Current stable version: 0.0.4. Release cadence: initial release, infrequent updates. Key differentiators: supports both Webpack and Vite, generates version files and ZIP archives, fully configurable via options (no environment variables), offers custom version formatting functions. Competes with simpler version injection plugins but provides more comprehensive build metadata collection.

Common errors

error Cannot find module 'adm-zip' ↓

cause Missing peer dependency adm-zip.

fix

Install adm-zip: npm install adm-zip

error Error: You forgot to add 'adm-zip' plugin... ↓

cause Vite or Webpack plugin missing required adm-zip.

fix

Install adm-zip and ensure it is in node_modules.

error TypeError: BuildVersionTracker is not a constructor ↓

cause Importing Webpack plugin from default export incorrectly or using wrong import path.

fix

Use 'import BuildVersionTracker from 'build-version-tracker'' or 'const BuildVersionTracker = require('build-version-tracker')'.

error Cannot find module 'build-version-tracker/vite' ↓

cause Trying to import Vite plugin without the /vite subpath or package missing.

fix

Use correct import: 'import viteVersionPlugin from 'build-version-tracker/vite'' and ensure package installed.

Warnings

gotcha Vite plugin import must use the '/vite' subpath; default import is only for Webpack plugin. ↓

fix Use import viteVersionPlugin from 'build-version-tracker/vite' for Vite, not from 'build-version-tracker'.

gotcha The 'adm-zip' peer dependency is required even if not using ZIP functionality; plugin might throw if missing. ↓

fix Install adm-zip: npm install adm-zip

deprecated The 'isBuild' option may be deprecated in future in favor of automatic detection. ↓

fix Check changelog; consider always setting isBuild: true for builds.

gotcha Requiring CommonJS module in Node.js <14 might fail due to ES module syntax. ↓

fix Use Node.js >=14 or transpile with Babel.

Install

npm install build-version-tracker

yarn add build-version-tracker

pnpm add build-version-tracker

Imports

BuildVersionTracker

wrong

const BuildVersionTracker = require('build-version-tracker')

correct

import BuildVersionTracker from 'build-version-tracker'

ESM default import for Webpack plugin.

viteVersionPlugin

wrong

import viteVersionPlugin from 'build-version-tracker'

correct

import viteVersionPlugin from 'build-version-tracker/vite'

For Vite plugin, must import from 'build-version-tracker/vite' subpath.

require for Webpack (CommonJS)

wrong

const BuildVersionTracker = require('build-version-tracker').default

correct

const BuildVersionTracker = require('build-version-tracker')

CommonJS require works directly; no .default needed.

require for Vite (CommonJS)

wrong

const viteVersionPlugin = require('build-version-tracker')

correct

const viteVersionPlugin = require('build-version-tracker/vite')

For Vite plugin in CJS, use require with subpath '/vite'.

Quickstart

Demonstrates both Webpack and Vite plugin usage with ESM imports and custom version formatting.

// Webpack plugin in ESM
import BuildVersionTracker from 'build-version-tracker';

export default {
  // other webpack config
  plugins: [
    new BuildVersionTracker({
      distPath: 'dist',
      isBuild: true,
      htmlName: 'index.html',
      formatVersion: (info) => `Version: ${info.time}, Branch: ${info.currentBranch}, User: ${info.userName}`,
      formatTextVersion: (info) => `Build: ${info.time}, Branch: ${info.currentBranch}, By: ${info.userName}`
    })
  ]
};

// Vite plugin in ESM
import viteVersionPlugin from 'build-version-tracker/vite';

export default {
  plugins: [
    viteVersionPlugin({
      distPath: 'dist',
      isBuild: true,
      htmlName: 'index.html'
    })
  ]
};