Local Obsidian plugin releases with `release-it`

.release-it.yaml

# This file is used to configure release-it
# Run `npx release-it` to release a regular release 
# Run `npx release-it --preRelease=beta` to start a pre-release
hooks:
  # This bump the manifest.json file with the new version before building
  'before:bump': 'npm_package_version=${version} node version-bump.mjs'
  'after:bump': npm run build
npm: false
git:
  getLatestTagFromAllRefs: true
  # Remove the [no ci] if you want to github actions to run on commit
  commitMessage: 'chore: release ${version} [no ci]'
  # commitMessage: 'chore: release ${version}'
github:
  # This will create a github release by opening the browser with a prefilled window
  # Set this to 'false' if you don't want to pre-fill the release
  release: true
  web: true

README.md

Releasing Obsidian Plugins locally with release-it

release-it is a generic CLI tool to automate versioning and package publishing-related tasks. This short guide explains how to use it to release Obsidian plugin (pre)releases locally.

Standard Releases

To create a standard release (major, minor, or patch):

npx release-it

This will:

1. Build your plugin assets locally
2. Update versions in manifest.json (regular releases only)
3. Create a Git tag
4. Generate a changelog
5. Create a GitHub release draft

Pre-releases

For beta versions or other pre-releases:

npx release-it --preRelease=beta

This adds the specified suffix (e.g. -beta.0) to your version number.

Dry runs

By adding --dry-run, you can run test the setup:

npx release-it --dry-run
npx release-it --preRelease=beta --dry-run

Asset Management

After running release-it, you must manually upload the following files to your GitHub release:

• main.js - Your compiled plugin code
• manifest.json - Plugin metadata and version information
• styles.css - Optional CSS styles for your plugin

Version Control Strategy

Release types affect version handling differently:

For standard releases, the manifest.json file is automatically updated with the new version. Proper Git tags and GitHub releases are created, ensuring compatibility with Obsidian's community plugin system.

For pre-releases (Beta), version numbers are appended with a -beta.X suffix. The manifest.json file remains unchanged in the main branch, allowing for testing without impacting the production version.

Installation and Prerequisites

Simply add the .release-it.yaml to your plugin root and add the semver package as a developer dependency:

npm i -D semver

version-bump.mjs

import { readFileSync, writeFileSync } from "node:fs";
const semver = await import("semver");

const targetVersion = process.env.npm_package_version;
const targetSemver = semver.parse(targetVersion);

// read minAppVersion from manifest.json and bump version to target version
const manifest = JSON.parse(readFileSync("manifest.json", "utf8"));
const { minAppVersion } = manifest;
// Write manifest.json with target version only if the target version is not a pre-release version
if (targetSemver.prerelease.length === 0) {
  manifest.version = targetVersion;
  writeFileSync("manifest.json", JSON.stringify(manifest, null, "\t"));

  // update versions.json with target version and minAppVersion from manifest.json
  // but only if the target version is not already in versions.json
  const versions = JSON.parse(readFileSync("versions.json", "utf8"));
  if (!Object.values(versions).includes(minAppVersion)) {
    versions[targetVersion] = minAppVersion;
    writeFileSync("versions.json", JSON.stringify(versions, null, "\t"));
  }
} else {
  console.log(
    `Skipping version bump in manifest.json for pre-release version: ${targetVersion}`
  );
}