dev-dump

Flexible, semver-compliant snapshot & prerelease version generator.

Generate deterministic, sortable prerelease versions for CI/CD pipelines, canary releases, feature branch deploys, and multi-stage release workflows — with zero dependencies.

Install

npm install -g dev-dump   # global
npm install -D dev-dump   # devDependency
npx dev-dump              # one-off

Quick Start

# Default: {preid}.{timestamp}.{hash}
npx dev-dump
# → 1.2.3-dev.202603171950.abc1234

# Alpha prerelease
npx dev-dump -p alpha
# → 1.2.3-alpha.202603171950.abc1234

# Auto-increment from npm registry
npx dev-dump -f "{preid}.{inc}" --from-registry
# → 1.2.3-dev.0  (next time: dev.1, dev.2, …)

# Canary release
npx dev-dump -f "canary.{hash}"
# → 1.2.3-canary.abc1234

# Feature branch snapshot
npx dev-dump -f "{branch}.{timestamp}.{hash}"
# → 1.2.3-feat-login.202603171950.abc1234

# Dry run (don't write package.json)
npx dev-dump --dry-run

# Capture for CI pipelines
VERSION=$(npx dev-dump --stdout-only)
echo "Publishing $VERSION"

Template Variables

The -f / --format flag defines the prerelease portion of the version. The base MAJOR.MINOR.PATCH is read from package.json (or overridden with --base).

| Variable | Description | Example | |---|---|---| | {preid} | Prerelease identifier (--preid) | dev, alpha, beta, rc | | {timestamp} | YYYYMMDDHHmm | 202603171950 | | {ts} | YYMMDDHHmm | 2603171950 | | {date} | YYYYMMDD | 20260317 | | {time} | HHmm | 1950 | | {hash} | Git short hash (7 chars) | abc1234 | | {hash-long} | Git full hash (40 chars) | abc1234567890… | | {inc} | Auto-increment counter (needs --from-registry) | 0, 1, 2 | | {branch} | Git branch name (sanitised) | feat-login | | {base} | MAJOR.MINOR.PATCH | 1.2.3 |

Options

| Option | Short | Default | Description | |---|---|---|---| | --preid <id> | -p | dev | Prerelease identifier | | --format <tpl> | -f | {preid}.{timestamp}.{hash} | Prerelease template | | --base <ver> | -b | from package.json | Override base version | | --from-registry | -r | false | Resolve base / {inc} from npm registry | | --tag <tag> | -t | latest | dist-tag for --from-registry | | --dry-run | -d | false | Print version without writing files | | --stdout-only | -s | false | Only output version to stdout | | --no-git-tag | | true | Don't create a git tag | | --cwd <path> | | . | Working directory | | --help | -h | | Show help | | --version | -v | | Show tool version |

Common Recipes

CI/CD Snapshot (default)

npx dev-dump
# 1.2.3-dev.202603171950.abc1234
npm publish --tag dev

Standard Prerelease Cycle

# alpha phase
npx dev-dump -p alpha -f "{preid}.{inc}" -r
# 1.2.3-alpha.0 → alpha.1 → alpha.2

# beta phase
npx dev-dump -p beta -f "{preid}.{inc}" -r
# 1.2.3-beta.0 → beta.1

# release candidate
npx dev-dump -p rc -f "{preid}.{inc}" -r
# 1.2.3-rc.0 → rc.1

# final release
npm version 1.2.3

Feature Branch Deploy

npx dev-dump -f "{branch}.{timestamp}.{hash}"
# 1.2.3-feat-login.202603171950.abc1234
npm publish --tag "$(git branch --show-current | tr '/' '-')"

Canary Release

npx dev-dump -f "canary.{hash}"
# 1.2.3-canary.abc1234
npm publish --tag canary

Override Base for Next Major

npx dev-dump -b 2.0.0 -p alpha
# 2.0.0-alpha.202603171950.abc1234

GitHub Actions Example

- name: Publish snapshot
  run: |
    VERSION=$(npx dev-dump --stdout-only)
    npm version "$VERSION" --no-git-tag-version
    npm publish --tag dev
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

SemVer Compliance

All generated versions are fully compliant with Semantic Versioning 2.0.0:

• Prerelease identifiers use only [0-9A-Za-z-]
• No leading zeros on numeric identifiers
• Empty identifiers are automatically removed
• Branch names and custom strings are sanitised (/ _ → -)
• Versions are validated with a strict SemVer regex before output
• Ordering is verified: timestamps naturally sort correctly, {inc} is monotonically increasing

Programmatic API

const {
  parseSemver,
  isValidSemver,
  semverCompare,
  sanitise,
  interpolate,
  buildVariables,
  resolveInc,
  resolveBaseFromRegistry,
} = require('dev-dump');

// Parse
parseSemver('1.2.3-dev.1');
// → { major: 1, minor: 2, patch: 3, prerelease: 'dev.1', build: '', base: '1.2.3' }

// Compare
semverCompare('1.0.0-alpha', '1.0.0-beta'); // → -1

// Sanitise branch names
sanitise('feature/my_branch'); // → 'feature-my-branch'

// Interpolate custom template
interpolate('{preid}.{timestamp}', { preid: 'dev', timestamp: '202603171950' });
// → 'dev.202603171950'

Zero Dependencies

This package has no runtime dependencies. It includes a built-in semver parser, comparator, and validator — everything needed in a single index.js file.

License

MIT