mkver

Easy access to your version and build metadata from within Node.js

Why?

Simple, reliable access to version and build information from within Node.js and Electron apps should be easy, without runtime dependencies.

Even if you push git SHAs into your package.json, after minification, asarification, and installation into platform-specific directory structures, you'll still be fighting __dirname bugs trying to find where your package.json went.

In TypeScript and ES6 module environments, there's a simple, minification-compatible and asar-compatible solution for importing information from outside your current file.

It's called import. Or for CommonJS users, require.

By writing build-specific information as constants in code within our codebase, consuming this metadata becomes trivial. Add it to your build pipeline, import it, and focus on the big problems.

What?

mkver produces either:

• Version.ts (the default, for TypeScript users)
• version.mjs (for JavaScript module users)
• version.js (for CommonJS users)
• version.cjs (for explicit CommonJS in ESM projects)

Each file contains your git SHA and version information exported as constants.

Example output

// Version.ts

export const version = "1.2.3-beta.4"
export const versionMajor = 1
export const versionMinor = 2
export const versionPatch = 3
export const versionPrerelease = ["beta", 4]
export const release = "1.2.3-beta.4+20220101105815"
export const gitSha = "dc336bc8e1ea6b4e2f393f98233839b6c23cb812"
export const gitDate = new Date(1641063495000)
export default {
  version,
  versionMajor,
  versionMinor,
  versionPatch,
  versionPrerelease,
  release,
  gitSha,
  gitDate,
}
Copy

The filename can be anything you want, but the file extension must be .ts, .mjs, .js, or .cjs.

It also creates a SemVer-compatible release tag in the format ${version}+${YYYYMMDDhhmmss of gitDate}, and a gitDate Date instance representing when the last git commit occurred.

Installation

Step 1: Add mkver to your package.json

npm i --save-dev mkver

Step 2: For TypeScript users

Add a pre... npm script to your package.json that runs mkver:

  "scripts": {
    ...
    "precompile": "mkver",
    "compile": "tsc",
    ...
  }
Copy

Step 2: For JavaScript module or CommonJS users

Add mkver as a pre... script for your test script and/or build pipeline in your package.json:

  "scripts": {
    ...
    "prebuild": "mkver ./lib/version.mjs", // or ./lib/version.js or ./lib/version.cjs
    "build": "webpack", // or whatever you use
    ...
  }
Copy

Step 3: Add to .gitignore

You should add your Version.ts, version.mjs, version.js, or version.cjs file to your project's .gitignore.

How

mkver is a simple, dependency-free, three-step tool:

1. mkver recursively searches for a package.json starting from the current directory and extracts the version value.
2. mkver executes git rev-parse HEAD to get the last commit SHA. Git must be available in your PATH.
3. mkver writes the output to the specified file (default: ./Version.ts). The file extension determines the output format (TypeScript, ESM, or CommonJS). Existing files will be overwritten.

If anything goes wrong, mkver will output errors to stderr and exit with a non-zero code.

Use with TypeScript or MJS modules

import { version, release } from "./Version"
Copy

Use with CommonJS

const { version, release } = require("./version") // Ensure the case matches your mkver output filename
Copy

Remember to specify mkver version.js (or version.cjs) in your npm script (see Installation Step 2 above).

Bash access to your version info

Need access to your release from a bash deploy script?

  # For CommonJS (.js or .cjs files):
  release=$(node -e "console.log(require('./path/to/version.js').release)")
  
  # For ESM (.mjs or .ts files):
  release=$(node -e "import('./path/to/version.mjs').then(m => console.log(m.release))")
Copy

Changelog

See CHANGELOG.md.