Version Management

Every release of your Tauri application carries a version number that users, auto‑updaters, and platform installers rely on. Getting that number right — and keeping it aligned with the actual changes you ship — is what version management is about. In a Tauri project, version management covers three main areas: choosing and incrementing the version string itself, writing release notes that tell users what happened, and maintaining a changelog that gives a complete technical history of your app.

Why Version Numbers Matter for Tauri Apps

A version number is not just a label. It is the signal your update system uses to decide whether to download new binaries. The Tauri auto‑updater plugin compares the installed app’s version against a remote JSON endpoint. If the remote version is newer according to semantic versioning rules, the updater fetches the update.

Beyond automatic updates, the version number appears in several places:

• Windows installers: the version field is mapped to a four‑part product version (e.g., 1.0.0.0). Tauri normalises your SemVer string to fit this requirement.
• macOS bundles: the version is written into the Info.plist file as both CFBundleShortVersionString and CFBundleVersion.
• Linux packages: the version is embedded in package metadata such as .deb control files.

A predictable versioning scheme builds user trust. When someone sees 2.3.1, they know they are on a patch release after 2.3.0. If you jump from 1.0 to 3.0 with no explanation, your users will wonder what they missed.

Semantic Versioning (SemVer)

Semantic versioning, or SemVer, is a convention that encodes information about the scope of changes directly into the version number. It uses three numeric segments separated by dots:

MAJOR.MINOR.PATCH

• MAJOR – you made changes that are incompatible with previous versions. Users need to pay attention when upgrading.
• MINOR – you added functionality in a way that does not break existing features.
• PATCH – you fixed bugs without changing the public behaviour of the app.

Tauri itself and its entire plugin ecosystem follow SemVer. You should do the same for your own app, because the auto‑updater, the build system, and platform packaging tools all expect a valid SemVer string.

Pre‑release and build metadata tags can be appended when needed:

1.0.0-alpha.1
1.0.0-beta.2
1.0.0+20250615

A pre‑release tag like -alpha.1 or -beta.2 is useful when you distribute early builds to testers and want the auto‑updater to only serve stable updates to most users.

Where the App Version Lives in a Tauri Project

In a Tauri v2 project, the official app version is stored in the tauri.conf.json file under the tauri.version field. This is the single source of truth that the build process reads.

{
  "$schema": "https://raw.githubusercontent.com/nicegui/tauri/dev/crates/tauri-cli/config.schema.json",
  "productName": "MyApp",
  "version": "1.2.3",
  "identifier": "com.mycompany.myapp",
  "build": {
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run build",
    "devUrl": "http://localhost:1420",
    "frontendDist": "../dist"
  },
  "app": {
    "withGlobalTauri": true,
    "windows": [],
    "security": {
      "csp": null
    }
  },
  "bundle": {
    "active": true,
    "targets": "all",
    "icon": ["icons/32x32.png", "icons/128x128.png", "icons/128x128@2x.png", "icons/icon.icns", "icons/icon.ico"]
  }
}

The important line is "version": "1.2.3". Every tauri build invocation picks up this field and stamps it into the compiled binaries.

You might also see version numbers in two other files: package.json (for the frontend) and src-tauri/Cargo.toml (for the Rust backend). These versions are used for dependency management and have no direct effect on the final app version, but keeping them in sync avoids confusion.

You can read the app version at runtime from both the frontend and the backend.

From a React component (using Tauri APIs):

import { getVersion } from "@tauri-apps/api/app";
import { useEffect, useState } from "react";
export default function App() {
  const [version, setVersion] = useState("");
  useEffect(() => {
    getVersion().then(setVersion);
  }, []);
  return <p>App version: {version}</p>;
}

getVersion reads the version from the tauri.conf.json that was embedded at build time. The returned value is a plain SemVer string.

From Rust code:

use tauri::Manager;
fn main() {
  tauri::Builder::default()
    .setup(|app| {
      let version = app.package_info().version.to_string();
      println!("App version: {}", version);
      Ok(())
    })
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
}

The call to app.package_info().version gives you the same version string. You can use it in an “About” window or to send the version to an analytics endpoint.

Incrementing the Version for a New Release

Every time you cut a release, you must decide which segment to bump and then update the version in tauri.conf.json. The simplest approach is to edit the file manually, but that is error‑prone. A more reliable workflow keeps the frontend’s package.json version as the primary driver and automatically synchronises it to the Tauri config.

Manual bump

1. Open src-tauri/tauri.conf.json.
2. Change the version field to the new SemVer string.
3. Optionally update the version fields in package.json and src-tauri/Cargo.toml if you want them to match.
4. Commit the changes.

Synchronised bump with npm and a small script

Many Tauri projects use React and already manage their frontend version with npm version. You can add a script that copies the version from package.json into tauri.conf.json immediately after the bump.

Create a file scripts/sync-version.mjs:

import { readFileSync, writeFileSync } from "fs";
const pkg = JSON.parse(readFileSync("package.json", "utf8"));
const tauriConfigPath = "src-tauri/tauri.conf.json";
const tauriConfig = JSON.parse(readFileSync(tauriConfigPath, "utf8"));
tauriConfig.version = pkg.version;
writeFileSync(tauriConfigPath, JSON.stringify(tauriConfig, null, 2) + "\n");
console.log(`Synced version ${pkg.version} to tauri.conf.json`);

The script reads the version from package.json, writes it into the Tauri config, and adds a trailing newline so Git does not complain about a missing end‑of‑line. To use it, add the script to package.json:

{
  "name": "my-tauri-app",
  "version": "1.2.3",
  "scripts": {
    "sync-version": "node scripts/sync-version.mjs"
  }
}

Now, when you prepare a release, you can run:

npm version patch   # bumps 1.2.3 → 1.2.4
npm run sync-version

npm version patch increments the patch segment, commits the change, and creates a Git tag. The sync script then carries that version into tauri.conf.json. You should stage the updated Tauri config and amend the commit or create a second one so the repository stays consistent.

Writing Release Notes

Release notes are the human‑readable summary you give to your users. They explain why they should care about an update. A good release note answers three questions:

• What changed?
• Does this affect how I use the app?
• Do I need to do anything before upgrading?

A simple, effective template for a Tauri app looks like this:

## 1.3.0 – Dark Mode & Linux Fixes
### Highlights
- The app now follows your system dark mode setting automatically.
### New Features
- Dark mode support with manual override in Settings.
- Linux: tray icon now shows a context menu.
### Bug Fixes
- Fixed a crash when starting on Windows machines without a GPU driver.
- Fixed blurry text on high‑DPI displays.
### Breaking Changes
- The keybinding Ctrl+Shift+S now opens Settings instead of Save. If you used the old shortcut, reassign it in Preferences.

Write release notes alongside your changelog, but do not just copy the raw commit history. Filter for what matters to a user: new buttons, fixed annoyances, anything that requires a manual step. If you use GitHub, GitLab, or a similar platform, publish the notes in your release page so they are easy to find.

Maintaining a Changelog

A changelog is the comprehensive, technical record of every notable change that went into a release. It helps contributors and maintainers understand the evolution of the project and is the foundation from which release notes are drafted.

The Keep a Changelog format is widely adopted and fits well with Tauri projects. It groups changes under clear headings:

# Changelog
## [1.2.0] - 2025-06-15
### Added
- System tray integration with minimize-to-tray option.
- `get_disk_space` command to query remaining disk space.
### Changed
- Window title now includes the currently opened file name.
### Fixed
- Race condition in updater that caused a second download on fast networks.
- Incorrect DPI scaling on monitors set to 125 %.
## [1.1.0] - 2025-05-22
### Added
- Auto‑updater support with the `tauri-plugin-updater`.

Place CHANGELOG.md in the repository root. Update it with every release. The entries become the source material for your release notes.

Automating Version Bumps and Changelog Generation

If you write commit messages that follow the Conventional Commits specification, you can automate the entire version‑bump and changelog‑generation workflow. Tools like standard-version or semantic-release read your commit history, determine the next version, update CHANGELOG.md, and bump version numbers in your files.

To set up standard-version for a Tauri project:

1. Install the tool and a plugin to keep the Tauri config in sync:

   npm install --save-dev standard-version
   

2. Add a configuration snippet in package.json that runs your sync script after the version is bumped:

   package.json
   {
     "standard-version": {
       "scripts": {
         "postbump": "node scripts/sync-version.mjs && git add src-tauri/tauri.conf.json"
       }
     }
   }
   

3. Now you can cut a release with a single command:

   npx standard-version
   

   Based on your commit messages since the last release, standard-version will:

   • bump the version in package.json,
   • run the sync script to update tauri.conf.json,
   • update CHANGELOG.md with the new release section,
   • create a Git commit and tag.

The result is a completely consistent version update with a populated changelog. The git add in the postbump script ensures the modified Tauri config is included in the release commit.

Prerelease Versions and Beta Testing

When you want to release a build to a small group of testers before pushing it to everyone, use a pre‑release tag:

1.3.0-beta.0
1.3.0-beta.1
1.3.0-rc.1

Set this directly in tauri.conf.json:

{
  "version": "1.3.0-beta.1"
}

The Tauri updater plugin can be configured to only offer stable updates by filtering out pre‑release versions on the server side. On the client side, the updater will consider a pre‑release version newer than a stable one of the same major.minor.patch? Actually, SemVer specifies that a pre‑release version has lower precedence than a normal version (e.g., 1.3.0-beta.1 < 1.3.0). This means if your stable users are on 1.2.0, the updater will see 1.3.0-beta.1 as newer than 1.2.0 and might offer the beta to them unless you explicitly separate the update channels. A common practice is to use a separate update endpoint for beta builds and point the updater to a different JSON URL only in your beta builds.

Common Mistakes and Pitfalls

Skipping the Tauri config version update

Running npm version but forgetting to sync tauri.conf.json is the most frequent error. The app appears to have the correct version in the frontend but the binary reports an older one, causing the auto‑updater to loop.

Using a non‑SemVer version

A version like 1.0 is not valid SemVer. Tauri’s build tools may tolerate it, but the auto‑updater will fail to parse it. Always use three numeric parts: 1.0.0.

Including breaking changes in a minor bump

If you rename a command or change a Tauri IPC signature, that is a breaking change. Bumping only the minor version tells users the update is safe, when it is not. They may install the update and find their workflows broken with no warning.

Releasing without any notes

Even a small patch release should have a one‑line note. Users who see an update notification with no information will hesitate to install it.

Not keeping changelog entries descriptive

A changelog entry that says only “fix stuff” helps nobody. Mention which component was affected and what the user‑visible change is.

Version management is the connective tissue between your code and your users. The version number itself tells the updater what to do, the release notes tell the user what to expect, and the changelog tells future maintainers what happened and why. When these three artefacts stay in lockstep — driven by a consistent SemVer scheme, backed by simple automation — releasing a Tauri application becomes a predictable, low‑stress routine.