Skip to content

previewRelease() and previewChangelog() ​

Compute what the next release does as data, without writing anything - the versions, the bump type, the commits and the reason of each package, the tags, the steps and the changelog entries.

ts
function previewRelease(options?: PreviewReleaseOptions): Promise<ReleasePreview>
function previewChangelog(options?: PreviewChangelogOptions): Promise<PreviewChangelog[]>

They are the implementation of the preview_release and preview_changelog tools of the MCP server, for a program that shows the release before it runs (an app, a dashboard). They write nothing, run no hook, ask nothing, and only use the network when you ask: fetchTags, checks, changelog.contributors. The profile, the config and the overrides apply as in release().

They print nothing: the warnings of the computation are in warnings (with the default level of the logger, or the logLevel of overrides), and the level of the logger is back to the one of before once they end. Several previews can run at the same time (several projects of an application): each one gets its own warnings.

Options ​

OptionDescription
cwdRoot of the project, process.cwd() by default
configName, configThe config to load (a name or a path, see Multiple configs), or a config already resolved
profile, overridesA profile, and options applied over the config ({ release: { social: false } })
type, preid, suffix, canaryWhat --minor, --preid, --suffix and --canary do
from, to, force, groupsThe range of the commits, --force, and the version groups to preview
fetchTagsRun git fetch --tags first, as the release does. Default: false, the local tags are used
checksCheck what would make the release fail: a version already published, a tag already on the remote. Default: false, it uses the network
changelogAdd the changelog entries to the preview: true for all of them, { package: 'core', contributors: false } for one (contributors may query the GitHub API)

ReleasePreview ​

ts
interface ReleasePreview {
  profile?: string // the profile applied
  canary: boolean
  versionMode: 'unified' | 'selective' | 'independent' | 'standalone' | 'groups'
  released: boolean // at least one package is released
  sets: PreviewSet[] // the project, or one per version group
  tags: string[] // the git tags the release creates
  steps: PreviewStep[] // every step of release, in order, with whether it runs
  problems: { kind: string, message: string }[] // with `checks`: what would make the release fail
  warnings: string[]
  changelogs: PreviewChangelog[] // with `changelog`
}

interface PreviewSet {
  group?: string
  title: string
  versionMode: 'unified' | 'selective' | 'independent' | 'standalone'
  released: boolean
  oldVersion?: string // unified and selective: the root version
  newVersion?: string
  bump?: PreviewBumpType
  tag?: string
  fromTag?: string
  commits: PreviewCommit[]
  packages: PreviewPackage[]
  notReleased: string[] // no commit, no bumped dependency
}

interface PreviewPackage {
  name: string
  path: string // relative to the project
  private: boolean
  oldVersion: string
  newVersion: string
  bump: 'major' | 'minor' | 'patch' | 'premajor' | 'preminor' | 'prepatch' | 'prerelease' | 'graduation' | 'canary'
  tag?: string
  reason: 'commits' | 'dependency' | 'graduation' | 'forced' | 'unified'
  commits: PreviewCommit[]
  dependency?: { chain: string[], group?: string, outOfRange?: { name: string, field: string, range: string | null, newVersion: string } }
  breakingPeerDependency?: string
}

interface PreviewStep {
  name: 'bump' | 'changelog' | 'publish' | 'commit-and-tag' | 'push' | 'provider-release' | 'social' | 'pr-comment'
  label: string
  enabled: boolean
  disabledBy?: string // `release.social`, `release.canary`
}

interface PreviewCommit {
  hash?: string // the full hash (none for the squash commit simulated by a merge preview)
  shortHash: string
  type: string // `feat`, `fix`...
  scope: string // empty without scope
  description: string
  breaking: boolean
  author?: string
}

interface PreviewChangelog {
  label: string
  file: string // `packages/core/CHANGELOG.md`
  packageName: string
  content: string // the markdown added at the top of the file
}

reason: 'dependency' comes with dependency: the chain of dependencies leading to the package, the version group releasing the dependency when it is another one, and for a version out of the published range of the package (a peer dependency, a workspace:*...) the range, the field and the new version. breakingPeerDependency names a peer dependency making a breaking change that the published range of the package rejects. The step names are the ones of the hooks and of the progress events.

Examples ​

ts
import { previewChangelog, previewRelease } from 'relizy'

const preview = await previewRelease({ profile: 'beta', checks: true })

if (!preview.released) {
  console.log('Nothing to release')
}

for (const set of preview.sets) {
  console.log(set.title, set.oldVersion, '->', set.newVersion)

  for (const pkg of set.packages) {
    console.log(`  ${pkg.name} ${pkg.oldVersion} -> ${pkg.newVersion} (${pkg.bump}, ${pkg.reason}, ${pkg.commits.length} commits)`)
  }
}

for (const problem of preview.problems) {
  console.error(problem.message)
}

const changelogs = await previewChangelog({ profile: 'beta', package: 'root' })
console.log(changelogs[0]?.content)

The same preview as the MCP tools: previewRelease({ changelog: true }) for the versions and the changelogs in one computation. previewChangelog({ package }) throws when the release does not release this package: the message lists the released ones.

See Also ​