@hyperfrontend/workspace/executors/versionversion
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 }
}
}
| Option | What it does |
|---|---|
--dryRun | Prints what would change and writes nothing |
--releaseAs | Forces the bump: major, minor or patch |
--tagPrefix | The tag prefix; defaults to {projectName}@ |
--skipCommit | Leaves the bump uncommitted |
--skipTag | Creates no tag; defaults to true, as tags are created after the publish |
--maxCommitFallback | How many commits the flow reads at most; defaults to 500 |
--scopeFiltering | Which commit scopes count for the project, beyond its own files |
--verbose, --quiet | More 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
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:
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
| Name | Type | Description |
|---|---|---|
§options | RunVersionOptions | Configuration 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§functionversionExecutor(
versionExecutor( options: VersionExecutorOptions, context: ExecutorContext): Promise< ExecutorResult>
Versions a project using
Key behaviors:
@hyperfrontend/versioning. Key behaviors:
- Uses npm registry as source of truth (not git tags)
- Tags as OUTPUT (created after publish), not INPUT
runVersion() for the core versioning logic, allowing the same logic to be reused by the version-batch executor.Parameters
| Name | Type | Description |
|---|---|---|
§options | VersionExecutorOptions | Configuration options for the version executor |
§context | ExecutorContext | The 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
The run a follow-up is called from.
Properties
Options for running version logic on a single project.
Properties
§
projects:Readonly< Record< string, ProjectConfiguration>>Every project of the workspace by name: the ones that pin the package are brought to the new version§
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 carryResult of running version logic on a single project.
Properties
What a version run did to a project, as a follow-up reads it.
Properties
What a
version target configures: the bump, the commit and the tag, and how commits are attributed to the project.Properties
§
Controls how commits are filtered and classified for this project:
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 includeexcludeScopes: Scopes to exclude even if files matchtrackDependencyChanges: Include dependency commits as indirectinfrastructure: 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).§
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
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