@hyperfrontend/workspace/executors/version

version

Versions a project from its conventional commits with @hyperfrontend/versioning, the npm registry being the source of truth for what is published: it bumps the manifest, writes the changelog entry, pins every workspace project that depends on the package to the new version, and commits.

{
  "version": {
    "executor": "@hyperfrontend/workspace:version",
    "options": { "maxCommitFallback": 500 }
  }
}
OptionWhat it does
--dryRunPrints what would change and writes nothing
--releaseAsForces the bump: major, minor or patch
--tagPrefixThe tag prefix; defaults to {projectName}@
--skipCommitLeaves the bump uncommitted
--skipTagCreates no tag; defaults to true, as tags are created after the publish
--maxCommitFallbackHow many commits the flow reads at most; defaults to 500
--scopeFilteringWhich commit scopes count for the project, beyond its own files
--verbose, --quietMore or less output

What the flow assumes

  • A commit's scope names a project: feat(my-utils): ... belongs to the project named my-utils.
  • A library is due a release when a commit touches code it ships, or when the graph selects its build for a change to a project its build target names as an input. A releasable commit to any file such an input names releases every library built with it, so these inputs should name the code that shapes the output. The input names engine and executorShared are reserved for the engine's own code in the workspace that develops it, and the flow leaves them out.
  • A package still below 1.0.0 takes a minor bump for a breaking change.
  • A run whose head commit is already the project's version commit does nothing, so the task is safe to repeat.

An executor that wraps this one passes follow-ups through runVersion: functions called after the bump and before the commit, each answering the files the commit must also carry. No configuration can set them.

API Reference§

ƒ Functions

§function

runVersion(options: RunVersionOptions): Promise<RunVersionResult>

Runs versioning logic for a single project.
This function contains the core versioning logic extracted from the executor, allowing it to be called directly by the version-batch executor without going through the executor interface.
Key behaviors:
  • Uses npm registry as source of truth (not git tags)
  • Performs safety checks (version commit detection, unstable git state)
  • Executes the versioning flow via @hyperfrontend/versioning
  • Updates dependent package versions
  • Tracks all modified files
Parameters
NameTypeDescription
§options
RunVersionOptionsConfiguration options for versioning
Returns
Promise<RunVersionResult>
Result containing success status, version info, and modified files
Examples

Versioning a project without committing

const result = await runVersion({
  projectName: 'my-lib',
  workspaceRoot: '/path/to/workspace',
  projectRoot: 'libs/my-lib',
  projects: context.projects,
  skipCommit: true,
  skipTag: true,
})

if (result.bumped) {
  console.log(`Bumped from ${result.previousVersion} to ${result.newVersion}`)
  console.log(`Modified files: ${result.modifiedFiles.join(', ')}`)
}

Carrying a follow-up's files into the version commit

import { writeFileSync } from 'node:fs'
import { join } from 'node:path'

const result = await runVersion({
  projectName: 'my-lib',
  workspaceRoot: '/path/to/workspace',
  projectRoot: 'libs/my-lib',
  projects: context.projects,
  followUps: [
    (bump, run) => {
      if (!run.dryRun) writeFileSync(join(run.workspaceRoot, 'docs/versions.md'), `${bump.packageName} ${bump.newVersion}\n`)
      return ['docs/versions.md']
    },
  ],
})
// => result.modifiedFiles ends with 'docs/versions.md', amended into the commit that records the bump
§function

versionExecutor(options: VersionExecutorOptions, context: ExecutorContext): Promise<ExecutorResult>

Versions a project using @hyperfrontend/versioning.
Key behaviors:
  • Uses npm registry as source of truth (not git tags)
  • Tags as OUTPUT (created after publish), not INPUT
This executor delegates to runVersion() for the core versioning logic, allowing the same logic to be reused by the version-batch executor.
Parameters
NameTypeDescription
§options
VersionExecutorOptionsConfiguration options for the version executor
§context
ExecutorContextThe workspace, the project and the target the task runs on
Returns
Promise<ExecutorResult>
Success status
Example

A `version` target attributing commits by scope and by file

{
  "targets": {
    "version": {
      "executor": "@hyperfrontend/workspace:version",
      "options": {
        "tagPrefix": "lib-core@",
        "scopeFiltering": { "strategy": "hybrid", "excludeScopes": ["ci", "docs-site"] }
      }
    }
  }
}
```
`npx hf run lib-core:version --dryRun` says what would be bumped; without the flag the bump, the changelog entry and the pins of the dependents are committed, and no tag is made until `--skipTag=false`.

◈ Interfaces

§interface

FollowUpRun

The run a follow-up is called from.
Properties
§readonly workspaceRoot:stringAbsolute path to the workspace root
§readonly dryRun:booleanWhether the run writes nothing; a follow-up then writes nothing either
§interface

RunVersionOptions

Options for running version logic on a single project.
Properties
§projectName:stringName of the project to version
§workspaceRoot:stringAbsolute path to workspace root
§projectRoot:stringProject root relative to workspace root
§projects:Readonly<Record<string, ProjectConfiguration>>Every project of the workspace by name: the ones that pin the package are brought to the new version
§skipCommit?:booleanSkip creating a git commit
§skipTag?:booleanSkip creating a git tag
§dryRun?:booleanPreview changes without applying
§verbose?:booleanEnable verbose logging
§quiet?:booleanSuppress non-error output
§releaseAs?:"major" | "minor" | "patch"Force a specific bump type
§tagPrefix?:stringVersion tag prefix
§scopeFiltering?:ScopeFilteringConfigScope filtering configuration
§maxCommitFallback?:numberUpper bound on the commit window the flow analyzes for bumps and changelogs
§followUps?:unknownCalled after the bump and before the commit, each answering the files the commit must also carry
§interface

RunVersionResult

Result of running version logic on a single project.
Properties
§success:booleanWhether the operation completed successfully
§bumped:booleanWhether a version bump actually occurred
§previousVersion:stringPrevious version (null if first release or skipped)
§newVersion:stringNew version (null if skipped)
§modifiedFiles:string[]All files modified during the operation
§error?:stringError message if operation failed
§flowResult?:FlowResultThe underlying flow result for advanced use cases
§interface

VersionBump

What a version run did to a project, as a follow-up reads it.
Properties
§readonly projectName:stringThe project's name
§readonly projectRoot:stringThe project's root, workspace-relative
§readonly packageName:stringThe name of the package the project carries
§readonly previousVersion:stringThe version before the bump, or null for a first release
§readonly newVersion:stringThe version the bump wrote
§interface

VersionExecutorOptions

What a version target configures: the bump, the commit and the tag, and how commits are attributed to the project.
Properties
§dryRun?:booleanSee what commands would be run, without committing to git or updating files.
§scopeFiltering?:ScopeFilteringConfigScope filtering configuration for commit classification and changelog generation.
Controls how commits are filtered and classified for this project:
  • strategy: Filtering strategy ('hybrid', 'scope-only', 'file-only', 'inferred')
  • includeScopes: Additional scopes to always include
  • excludeScopes: Scopes to exclude even if files match
  • trackDependencyChanges: Include dependency commits as indirect
  • infrastructure: Infrastructure path and scope tracking
§maxCommitFallback?:numberUpper bound on the commit window the flow analyzes for bumps and changelogs.
§releaseAs?:"major" | "minor" | "patch"Manually increment the version by that keyword (major, minor, patch).
§tagPrefix?:stringVersion tag prefix. Default is '{projectName}@' in independent mode.
§skipCommit?:booleanAllows to skip making a commit when bumping a version.
§skipTag?:booleanAllows to skip tagging the release. Default: true (tags created after publish).
§verbose?:booleanEnable verbose output for debugging. Shows additional details about each step.
§quiet?:booleanSuppress all non-error output.
§followUps?:unknownCalled after the bump and before the commit that records it, each answering the files the commit must also carry. No configuration sets this; an executor that wraps this one passes it.

◆ Types

§type

FollowUp

Called after a project is bumped and before the commit that records the bump. It answers the workspace-relative files it changed, and the commit carries them with the bump.
type FollowUp = (bump: VersionBump, run: FollowUpRun) => unknown