Repository files navigation

Easy access to your version and build metadata from withinNode.js

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 yourpackage.json, after minification,asarification, and installation into platform-specific directory structures, you'll still be fighting__dirname bugs trying to find where yourpackage.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 calledimport. Or forCommonJS users,require.

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

mkver produces either:

• Version.ts (the default, forTypeScript users)
• version.mjs (forJavaScript module users)
• version.js (forCommonJS users)
• version.cjs (for explicitCommonJS in ESM projects)

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

// Version.tsexportconstversion="1.2.3-beta.4";exportconstversionMajor=1;exportconstversionMinor=2;exportconstversionPatch=3;exportconstversionPrerelease=["beta",4];exportconstrelease="1.2.3-beta.4+20220101105815";exportconstgitSha="dc336bc8e1ea6b4e2f393f98233839b6c23cb812";exportconstgitDate=newDate(1641063495000);exportdefault{  version,  versionMajor,  versionMinor,  versionPatch,  versionPrerelease,  release,  gitSha,  gitDate,};

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

It also creates aSemVer-compatiblerelease tag in the format${version}+${YYYYMMDDhhmmss of gitDate}, and agitDateDate instance representing when the last git commit occurred.

mkver itself is distributed as a CommonJS package to ensure maximum compatibility across different Node.js environments and platforms. While the tool internally uses ES modules during development, the distributed package uses CommonJS to avoid compatibility issues that can arise with ESM on certain platforms (particularly Windows).

However,mkver generates output files in whatever format you need:

• TypeScript (.ts) with ES module exports
• ES modules (.mjs) with ES module exports
• CommonJS (.js or.cjs) with CommonJS exports

The output format is determined solely by the file extension you specify.

npm i --save-dev mkver

Add apre... npm script to yourpackage.json that runsmkver:

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

Addmkver as apre... script for your test script and/or build pipeline in yourpackage.json:

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

You should add yourVersion.ts,version.mjs,version.js, orversion.cjs file toyour project's.gitignore.

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

1. mkver recursively searches for apackage.json starting from the current directory and extracts theversion value.
2. mkver executesgit 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 tostderr and exit with a non-zero code.

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

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

Remember to specifymkver version.js (orversion.cjs) in your npm script (see Installation Step 2 above).

Need access to yourrelease 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))")

SeeCHANGELOG.md.