# version Versions a project from its conventional commits with [`@hyperfrontend/versioning`](https://www.hyperfrontend.dev/docs/libraries/versioning.md), 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. ```json { "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`](https://www.hyperfrontend.dev/docs/libraries/workspace/executors/version/#api-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 #### runVersion ```typescript function runVersion(options: RunVersionOptions): Promise ``` 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** | Name | Type | Description | | --- | --- | --- | | `options` | `RunVersionOptions` | Configuration options for versioning | **Returns** `Promise`: Result containing success status, version info, and modified files **Example: Versioning a project without committing** ```typescript 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(', ')}`) } ``` **Example: Carrying a follow-up's files into the version commit** ```typescript 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 ``` #### versionExecutor ```typescript function versionExecutor(options: VersionExecutorOptions, context: ExecutorContext): Promise ``` 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** | 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`: Success status **Example: A `version` target attributing commits by scope and by file** ```json { "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 #### FollowUpRun The run a follow-up is called from. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly workspaceRoot` | `string` | Absolute path to the workspace root | | `readonly dryRun` | `boolean` | Whether the run writes nothing; a follow-up then writes nothing either | #### RunVersionOptions Options for running version logic on a single project. **Properties** | Name | Type | Description | | --- | --- | --- | | `projectName` | `string` | Name of the project to version | | `workspaceRoot` | `string` | Absolute path to workspace root | | `projectRoot` | `string` | Project root relative to workspace root | | `projects` | `Readonly>` | Every project of the workspace by name: the ones that pin the package are brought to the new version | | `skipCommit?` | `boolean` | Skip creating a git commit | | `skipTag?` | `boolean` | Skip creating a git tag | | `dryRun?` | `boolean` | Preview changes without applying | | `verbose?` | `boolean` | Enable verbose logging | | `quiet?` | `boolean` | Suppress non-error output | | `releaseAs?` | `"major" \| "minor" \| "patch"` | Force a specific bump type | | `tagPrefix?` | `string` | Version tag prefix | | `scopeFiltering?` | `ScopeFilteringConfig` | Scope filtering configuration | | `maxCommitFallback?` | `number` | Upper bound on the commit window the flow analyzes for bumps and changelogs | | `followUps?` | `unknown` | Called after the bump and before the commit, each answering the files the commit must also carry | #### RunVersionResult Result of running version logic on a single project. **Properties** | Name | Type | Description | | --- | --- | --- | | `success` | `boolean` | Whether the operation completed successfully | | `bumped` | `boolean` | Whether a version bump actually occurred | | `previousVersion` | `string` | Previous version (null if first release or skipped) | | `newVersion` | `string` | New version (null if skipped) | | `modifiedFiles` | `string[]` | All files modified during the operation | | `error?` | `string` | Error message if operation failed | | `flowResult?` | `FlowResult` | The underlying flow result for advanced use cases | #### VersionBump What a version run did to a project, as a follow-up reads it. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly projectName` | `string` | The project's name | | `readonly projectRoot` | `string` | The project's root, workspace-relative | | `readonly packageName` | `string` | The name of the package the project carries | | `readonly previousVersion` | `string` | The version before the bump, or null for a first release | | `readonly newVersion` | `string` | The version the bump wrote | #### VersionExecutorOptions What a `version` target configures: the bump, the commit and the tag, and how commits are attributed to the project. **Properties** | Name | Type | Description | | --- | --- | --- | | `dryRun?` | `boolean` | See what commands would be run, without committing to git or updating files. | | `scopeFiltering?` | `ScopeFilteringConfig` | Scope 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?` | `number` | Upper 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?` | `string` | Version tag prefix. Default is '{projectName}@' in independent mode. | | `skipCommit?` | `boolean` | Allows to skip making a commit when bumping a version. | | `skipTag?` | `boolean` | Allows to skip tagging the release. Default: true (tags created after publish). | | `verbose?` | `boolean` | Enable verbose output for debugging. Shows additional details about each step. | | `quiet?` | `boolean` | Suppress all non-error output. | | `followUps?` | `unknown` | Called 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 #### 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. ```typescript type FollowUp = (bump: VersionBump, run: FollowUpRun) => unknown ``` --- Canonical page: https://www.hyperfrontend.dev/docs/libraries/workspace/executors/version/ This file: https://www.hyperfrontend.dev/docs/libraries/workspace/executors/version.md Documentation index: https://www.hyperfrontend.dev/llms.txt