{"id":14978524,"url":"https://github.com/photostructure/mkver","last_synced_at":"2025-10-28T10:32:57.002Z","repository":{"id":46833607,"uuid":"121985437","full_name":"photostructure/mkver","owner":"photostructure","description":"Node.js access to your app's version and release metadata","archived":false,"fork":false,"pushed_at":"2024-10-20T17:12:03.000Z","size":312,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-07T17:12:13.386Z","etag":null,"topics":["developer-tools","devops-tools","electron","electron-builder","electronjs","metadata","nodejs","typescript","versioning","versions"],"latest_commit_sha":null,"homepage":"https://photostructure.github.io/mkver","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/photostructure.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-02-18T19:57:00.000Z","updated_at":"2024-10-20T17:12:06.000Z","dependencies_parsed_at":"2024-03-28T03:40:17.702Z","dependency_job_id":"e9b05b42-de2d-47e6-8d30-b3c631170077","html_url":"https://github.com/photostructure/mkver","commit_stats":{"total_commits":143,"total_committers":5,"mean_commits":28.6,"dds":0.2797202797202797,"last_synced_commit":"85ec9e1be7b36cce920ed96b1958c03a761a00a0"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/photostructure%2Fmkver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/photostructure%2Fmkver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/photostructure%2Fmkver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/photostructure%2Fmkver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/photostructure","download_url":"https://codeload.github.com/photostructure/mkver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238638121,"owners_count":19505536,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["developer-tools","devops-tools","electron","electron-builder","electronjs","metadata","nodejs","typescript","versioning","versions"],"created_at":"2024-09-24T13:57:50.890Z","updated_at":"2025-10-28T10:32:56.995Z","avatar_url":"https://github.com/photostructure.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"**Easy access to your version and build metadata from within\n[Node.js](https://nodejs.org/)**\n\n[![npm version](https://img.shields.io/npm/v/mkver.svg)](https://www.npmjs.com/package/mkver)\n[![Build \u0026 Release](https://github.com/photostructure/mkver/actions/workflows/build.yml/badge.svg)](https://github.com/photostructure/mkver/actions/workflows/build.yml)\n[![CodeQL](https://github.com/photostructure/mkver/actions/workflows/codeql.yml/badge.svg)](https://github.com/photostructure/mkver/actions/workflows/codeql.yml)\n\n## Why?\n\nSimple, reliable access to version and build information from within Node.js and Electron apps should be easy, without runtime dependencies.\n\nEven if you push git SHAs into your `package.json`, after minification, `asar`ification, and installation into platform-specific directory structures, you'll still be fighting `__dirname` bugs trying to find where your `package.json` went.\n\nIn TypeScript and ES6 module environments, there's a simple, minification-compatible and asar-compatible solution for importing information from outside your current file.\n\nIt's called `import`. Or for [CommonJS](https://en.wikipedia.org/wiki/CommonJS) users, `require`.\n\nBy 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.\n\n## What?\n\n`mkver` produces either:\n\n- `Version.ts` (the default, for [TypeScript](https://www.typescriptlang.org/) users)\n- `version.mjs` (for [JavaScript module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) users)\n- `version.js` (for [CommonJS](https://en.wikipedia.org/wiki/CommonJS) users)\n- `version.cjs` (for explicit [CommonJS](https://en.wikipedia.org/wiki/CommonJS) in ESM projects)\n\nEach file contains your git SHA and version information exported as constants.\n\n## Example output\n\n```typescript\n// Version.ts\n\nexport const version = \"1.2.3-beta.4\";\nexport const versionMajor = 1;\nexport const versionMinor = 2;\nexport const versionPatch = 3;\nexport const versionPrerelease = [\"beta\", 4];\nexport const release = \"1.2.3-beta.4+20220101105815\";\nexport const gitSha = \"dc336bc8e1ea6b4e2f393f98233839b6c23cb812\";\nexport const gitDate = new Date(1641063495000);\nexport default {\n  version,\n  versionMajor,\n  versionMinor,\n  versionPatch,\n  versionPrerelease,\n  release,\n  gitSha,\n  gitDate,\n};\n```\n\nThe filename can be anything you want as long as the file extension is:\n\n- `.ts`,\n- `.mjs`,\n- `.js`, or\n- `.cjs`.\n\nIt also creates a [SemVer-compatible `release` field](https://semver.org/#spec-item-10) in the format `${version}+${YYYYMMDDhhmmss of gitDate}`, and a `gitDate` `Date` instance representing when the last git commit occurred.\n\n## Module Format\n\n`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).\n\nHowever, `mkver` generates output files in whatever format you need:\n\n- TypeScript (`.ts`) with ES module exports\n- ES modules (`.mjs`) with ES module exports\n- CommonJS (`.js` or `.cjs`) with CommonJS exports\n\nThe output format is determined solely by the file extension you specify.\n\n## Installation\n\n### Step 1: Add `mkver` to your package.json\n\n`npm i --save-dev mkver`\n\n### Step 2: For TypeScript users\n\nAdd a `pre...` npm script to your `package.json` that runs `mkver`:\n\n```json\n  \"scripts\": {\n    ...\n    \"precompile\": \"mkver\",\n    \"compile\": \"tsc\",\n    ...\n  }\n```\n\n### Step 2: For JavaScript module or CommonJS users\n\nAdd `mkver` as a `pre...` script for your test script and/or build pipeline in your `package.json`:\n\n```js\n  \"scripts\": {\n    ...\n    \"prebuild\": \"mkver ./lib/version.mjs\", // or ./lib/version.js or ./lib/version.cjs\n    \"build\": \"webpack\", // or whatever you use\n    ...\n  }\n```\n\n### Step 3: Add to .gitignore\n\nYou should add your `Version.ts`, `version.mjs`, `version.js`, or `version.cjs` file to\nyour project's `.gitignore`.\n\n## Usage\n\n```bash\nmkver [FILE]\n```\n\nWhere `FILE` is optional and defaults to `./Version.ts`.\n\n### CLI Options\n\n- `-h, --help` - Show help message\n- `-v, --version` - Show version number\n\n### Examples\n\n```bash\n# Generate Version.ts (default)\nmkver\n\n# Generate a specific file\nmkver ./src/version.mjs\n\n# Show version\nmkver --version\n\n# Show help\nmkver --help\n```\n\n## How\n\n`mkver` is a simple, dependency-free, three-step tool:\n\n1. `mkver` recursively searches for a `package.json` starting from the current directory and extracts the `version` value.\n2. `mkver` executes `git rev-parse HEAD` to get the last commit SHA. Git must be available in your PATH.\n3. `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.\n\nIf anything goes wrong, `mkver` will output (hopefully) helpful error messages to `stderr` and exit with a non-zero code.\n\n### Use with TypeScript or MJS modules\n\n```ts\nimport { version, release } from \"./Version\";\n```\n\n### Use with CommonJS\n\n```js\nconst { version, release } = require(\"./version\"); // Ensure the case matches your mkver output filename\n```\n\nRemember to specify `mkver version.js` (or `version.cjs`) in your npm script (see Installation Step 2 above).\n\n## Bash access to your version info\n\nNeed access to your `release` from a bash deploy script?\n\n```sh\n  # For CommonJS (.js or .cjs files):\n  release=$(node -e \"console.log(require('./path/to/version.js').release)\")\n\n  # For ESM (.mjs or .ts files):\n  release=$(node -e \"import('./path/to/version.mjs').then(m =\u003e console.log(m.release))\")\n```\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphotostructure%2Fmkver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphotostructure%2Fmkver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphotostructure%2Fmkver/lists"}