mkver
Version:
Node.js access to your app's version and release metadata
83 lines (76 loc) • 20.9 kB
HTML
<html class="default" lang="en" data-base="./"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>mkver - v3.0.2</title><meta name="description" content="Documentation for mkver"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="index.html" class="title">mkver - v3.0.2</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h1>mkver - v3.0.2</h1></div><div class="tsd-panel tsd-typography"><h1 id="mkver" class="tsd-anchor-link">mkver<a href="#mkver" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h1><p><strong>Easy access to your version and build metadata from within
<a href="https://nodejs.org/">Node.js</a></strong></p>
<p><a href="https://www.npmjs.com/package/mkver"><img src="https://img.shields.io/npm/v/mkver.svg" alt="npm version"></a>
<a href="https://github.com/photostructure/mkver/actions/workflows/node.js.yml"><img src="https://github.com/photostructure/mkver/actions/workflows/node.js.yml/badge.svg" alt="Node.js CI"></a>
<a href="https://github.com/photostructure/mkver/actions/workflows/codeql.yml"><img src="https://github.com/photostructure/mkver/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a></p>
<h2 id="why" class="tsd-anchor-link">Why?<a href="#why" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Simple, reliable, no-runtime-dependency access to version and build
information from within node and Electron apps should be easy.</p>
<p>Even if you push git SHAs into your <code>package.json</code>, after
minification, <code>asar</code>ification and installation into who-knows-where
platform-specific directory structures, you'll still be fighting
<code>__dirname</code> bugs trying to find where your <code>package.json</code> went.</p>
<p>In TypeScript and ES6 Module worlds, there's a super simple,
minification-compatible and asar-compatible solution to importing information
from outside your current file, and it's great.</p>
<p>It's called <code>import</code>. Or for you <a href="https://en.wikipedia.org/wiki/CommonJS">old-skool
kids</a>, <code>require</code>.</p>
<p>If we can write build-specific information as constants <strong>as code</strong>, living in
our codebase, consumption of this metadata becomes trivial. Add it to your build
pipeline, import the thing, and then solve the Big Problems.</p>
<h2 id="what" class="tsd-anchor-link">What?<a href="#what" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p><code>mkver</code> produces either:</p>
<ul>
<li>a <code>Version.ts</code> (the default, for <a href="https://www.typescriptlang.org/">TypeScript</a>
users),</li>
<li>a <code>version.mjs</code> (for <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules">JavaScript
module
users</a>),
or</li>
<li>a <code>version.js</code> (if you're using
<a href="https://en.wikipedia.org/wiki/CommonJS">CommonJS</a>), or</li>
<li>a <code>version.cjs</code> (for explicit <a href="https://en.wikipedia.org/wiki/CommonJS">CommonJS</a>
in ESM projects) with your git SHA and version information exported as constants.</li>
</ul>
<h2 id="example-output" class="tsd-anchor-link">Example output<a href="#example-output" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><pre><code class="typescript"><span class="hl-0">// Version.ts</span><br/><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-3">const</span><span class="hl-2"> </span><span class="hl-4">version</span><span class="hl-2"> = </span><span class="hl-5">"1.2.3-beta.4"</span><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-3">const</span><span class="hl-2"> </span><span class="hl-4">versionMajor</span><span class="hl-2"> = </span><span class="hl-6">1</span><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-3">const</span><span class="hl-2"> </span><span class="hl-4">versionMinor</span><span class="hl-2"> = </span><span class="hl-6">2</span><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-3">const</span><span class="hl-2"> </span><span class="hl-4">versionPatch</span><span class="hl-2"> = </span><span class="hl-6">3</span><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-3">const</span><span class="hl-2"> </span><span class="hl-4">versionPrerelease</span><span class="hl-2"> = [</span><span class="hl-5">"beta"</span><span class="hl-2">, </span><span class="hl-6">4</span><span class="hl-2">]</span><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-3">const</span><span class="hl-2"> </span><span class="hl-4">release</span><span class="hl-2"> = </span><span class="hl-5">"1.2.3-beta.4+20220101105815"</span><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-3">const</span><span class="hl-2"> </span><span class="hl-4">gitSha</span><span class="hl-2"> = </span><span class="hl-5">"dc336bc8e1ea6b4e2f393f98233839b6c23cb812"</span><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-3">const</span><span class="hl-2"> </span><span class="hl-4">gitDate</span><span class="hl-2"> = </span><span class="hl-3">new</span><span class="hl-2"> </span><span class="hl-7">Date</span><span class="hl-2">(</span><span class="hl-6">1641063495000</span><span class="hl-2">)</span><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-1">default</span><span class="hl-2"> {</span><br/><span class="hl-2"> </span><span class="hl-8">version</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-8">versionMajor</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-8">versionMinor</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-8">versionPatch</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-8">versionPrerelease</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-8">release</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-8">gitSha</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-8">gitDate</span><span class="hl-2">,</span><br/><span class="hl-2">}</span>
</code><button type="button">Copy</button></pre>
<p>The filename can be anything you want, but the file extension must be <code>.ts</code>,
<code>.mjs</code>, <code>.js</code>, or <code>.cjs</code>.</p>
<p>For extra credit, it also creates a <a href="https://semver.org/#spec-item-10">SemVer-compatible <code>release</code>
tag</a> that looks like
<code>${version}+${YYYYMMDDhhmmss of gitDate}</code>, and a <code>gitDate</code>, which is a <code>Date</code>
instance of when that last git commit happened.</p>
<h2 id="installation" class="tsd-anchor-link">Installation<a href="#installation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><h3 id="step-1-add-mkver-to-your-packagejson" class="tsd-anchor-link">Step 1: add <code>mkver</code> to your package.json<a href="#step-1-add-mkver-to-your-packagejson" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p><code>npm i --save-dev mkver</code></p>
<h3 id="step-2-for-typescript-users" class="tsd-anchor-link">Step 2: For TypeScript users<a href="#step-2-for-typescript-users" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Add a <code>pre...</code> npm script to your <code>package.json</code> that runs
<code>mkver</code>:</p>
<pre><code class="json"><span class="hl-2"> </span><span class="hl-5">"scripts"</span><span class="hl-2">: {</span><br/><span class="hl-2"> </span><span class="hl-9">...</span><br/><span class="hl-2"> </span><span class="hl-10">"precompile"</span><span class="hl-2">: </span><span class="hl-5">"mkver"</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-10">"compile"</span><span class="hl-2">: </span><span class="hl-5">"tsc"</span><span class="hl-2">,</span><br/><span class="hl-2"> </span><span class="hl-9">...</span><br/><span class="hl-2"> }</span>
</code><button type="button">Copy</button></pre>
<h3 id="step-2-for-javascript-module-or-commonjs-users" class="tsd-anchor-link">Step 2: For JavaScript module or CommonJS users<a href="#step-2-for-javascript-module-or-commonjs-users" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Add <code>mkver</code> as a <code>pre...</code> script for your test script and/or your
webpack/gulp/grunt/browserify pipeline in your <code>package.json</code>:</p>
<pre><code class="js"><span class="hl-2"> </span><span class="hl-5">"scripts"</span><span class="hl-2">: {</span><br/><span class="hl-2"> ...</span><br/><span class="hl-2"> </span><span class="hl-5">"prebuild"</span><span class="hl-2">: </span><span class="hl-5">"mkver ./lib/version.mjs"</span><span class="hl-2">, </span><span class="hl-0">// or ./lib/version.js or ./lib/version.cjs</span><br/><span class="hl-2"> </span><span class="hl-5">"build"</span><span class="hl-8">:</span><span class="hl-2"> </span><span class="hl-5">"webpack"</span><span class="hl-2">, </span><span class="hl-0">// or whatever you use</span><br/><span class="hl-2"> ...</span><br/><span class="hl-2"> }</span>
</code><button type="button">Copy</button></pre>
<h3 id="step-3-add-to-gitignore" class="tsd-anchor-link">Step 3: Add to .gitignore<a href="#step-3-add-to-gitignore" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>You should add your <code>Version.ts</code>, <code>version.mjs</code>, <code>version.js</code>, or <code>version.cjs</code> file to
your project's <code>.gitignore</code>.</p>
<h2 id="how" class="tsd-anchor-link">How<a href="#how" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p><code>mkver</code> is a pretty simple, no-dependencies, three-step, one-trick pony:</p>
<ol>
<li><code>mkver</code> first looks for a <code>package.json</code> in <code>.</code>, then <code>..</code>, then <code>../..</code>,
etc, and extracts the <code>version</code> value.</li>
<li><code>mkver</code> then
<a href="https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback">execs</a>
<code>git rev-parse HEAD</code> to get the last commit SHA. Having <code>git</code> available to
the calling shell is a prerequisite. Please don't file a bug report for this.</li>
<li>Finally, <code>mkver</code> writes the contents to the first argument given to <code>mkver</code>,
which can include a subdirectory. The default output is <code>./Version.ts</code>.
Existing files with that name will be overwritten. <code>mkver</code> uses the file
extension to determine what format (TypeScript, ESM, or CommonJS) to render the
output.</li>
</ol>
<p>If anything goes wrong, expect output on <code>stderr</code>, and a non-zero exit code.</p>
<h3 id="use-with-typescript-or-mjs-modules" class="tsd-anchor-link">Use with TypeScript or MJS modules<a href="#use-with-typescript-or-mjs-modules" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="ts"><span class="hl-1">import</span><span class="hl-2"> { </span><span class="hl-8">version</span><span class="hl-2">, </span><span class="hl-8">release</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-5">"./Version"</span>
</code><button type="button">Copy</button></pre>
<h3 id="use-with-commonjs" class="tsd-anchor-link">Use with CommonJS<a href="#use-with-commonjs" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="js"><span class="hl-3">const</span><span class="hl-2"> { </span><span class="hl-4">version</span><span class="hl-2">, </span><span class="hl-4">release</span><span class="hl-2"> } = </span><span class="hl-7">require</span><span class="hl-2">(</span><span class="hl-5">"./version"</span><span class="hl-2">) </span><span class="hl-0">// < mind the case matches whatever you give mkver</span>
</code><button type="button">Copy</button></pre>
<p>Remember to <code>mkver version.js</code> (or <code>version.cjs</code>) in your npm script (see the Installation's "Step 2" above!)</p>
<h2 id="bash-access-to-your-version-info" class="tsd-anchor-link">Bash access to your version info<a href="#bash-access-to-your-version-info" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Need access to your <code>release</code> from, say, your deploy script written in <code>bash</code>?</p>
<pre><code class="sh"><span class="hl-2"> </span><span class="hl-0"># For CommonJS (.js or .cjs files):</span><br/><span class="hl-2"> </span><span class="hl-8">release</span><span class="hl-2">=$(</span><span class="hl-7">node</span><span class="hl-2"> </span><span class="hl-3">-e</span><span class="hl-2"> </span><span class="hl-5">"console.log(require('./path/to/version.js').release)"</span><span class="hl-2">)</span><br/><span class="hl-2"> </span><br/><span class="hl-2"> </span><span class="hl-0"># For ESM (.mjs or .ts files):</span><br/><span class="hl-2"> </span><span class="hl-8">release</span><span class="hl-2">=$(</span><span class="hl-7">node</span><span class="hl-2"> </span><span class="hl-3">-e</span><span class="hl-2"> </span><span class="hl-5">"import('./path/to/version.mjs').then(m => console.log(m.release))"</span><span class="hl-2">)</span>
</code><button type="button">Copy</button></pre>
<h2 id="changelog" class="tsd-anchor-link">Changelog<a href="#changelog" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>See <a href="media/CHANGELOG.md">CHANGELOG.md</a>.</p>
</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#mkver"><span>mkver</span></a><ul><li><a href="#why"><span>Why?</span></a></li><li><a href="#what"><span>What?</span></a></li><li><a href="#example-output"><span>Example output</span></a></li><li><a href="#installation"><span>Installation</span></a></li><li><ul><li><a href="#step-1-add-mkver-to-your-packagejson"><span>Step 1: add mkver to your package.json</span></a></li><li><a href="#step-2-for-typescript-users"><span>Step 2: <wbr/>For <wbr/>Type<wbr/>Script users</span></a></li><li><a href="#step-2-for-javascript-module-or-commonjs-users"><span>Step 2: <wbr/>For <wbr/>Java<wbr/>Script module or <wbr/>Common<wbr/>JS users</span></a></li><li><a href="#step-3-add-to-gitignore"><span>Step 3: <wbr/>Add to .gitignore</span></a></li></ul></li><li><a href="#how"><span>How</span></a></li><li><ul><li><a href="#use-with-typescript-or-mjs-modules"><span>Use with <wbr/>Type<wbr/>Script or <wbr/>MJS modules</span></a></li><li><a href="#use-with-commonjs"><span>Use with <wbr/>Common<wbr/>JS</span></a></li></ul></li><li><a href="#bash-access-to-your-version-info"><span>Bash access to your version info</span></a></li><li><a href="#changelog"><span>Changelog</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html">mkver - v3.0.2</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>