Build Configuration

A Tauri app that runs on your machine with tauri dev is not yet ready for other people to use. Development mode prioritizes fast feedback — hot reloading, unoptimized bundles, debug symbols, and a dev server that serves your frontend. Shipping to users requires a different set of priorities: small binaries, fast startup, and the guarantee that the app will run on a machine that does not have Node.js, Rust, or any development tool installed.

Build configuration is the bridge between those two modes. It lives across two files — tauri.conf.json for frontend wiring and Cargo.toml for Rust compilation — and it touches every platform you intend to target. The decisions you make here determine how large your final binary is, how quickly it launches, and whether it works at all on a given operating system.

What Build Configuration Covers

The build configuration for a Tauri v2 app spans three connected areas, each with its own detailed page in this section.

Preparing for Production is about telling Tauri where your frontend assets are, what command builds them, and how the frontend and Rust backend connect when there is no dev server running. A misconfigured frontendDist path or a missing beforeBuildCommand is the most common reason a Tauri build fails silently or produces an app that shows a blank window.

Optimizing Builds moves into the Rust compilation pipeline. The default Cargo build settings favor compile speed over output quality. For a shipping application, you want the opposite: the smallest possible binary that runs as fast as the compiler can make it. This means configuring link-time optimization, stripping debug symbols, and choosing the right optimization level — all in Cargo.toml.

Platform Requirements is the reality check. Each operating system your app targets needs specific system libraries installed on the build machine. Linux requires webkit2gtk-4.1 and several other packages. Windows needs the WebView2 runtime and the MSVC build tools. macOS requires Xcode. Missing any of these does not produce a polite error message — the build simply fails with linker errors that are hard to decipher if you have not seen them before.

These three areas are not sequential steps you complete one after another. They overlap and interact. A build optimization that works on macOS might break the Linux build if it strips something the linker needs. A platform dependency installed on your CI runner might be the wrong version for your target distribution. The detailed pages in this section walk through each area, but the overview that follows gives you the mental model to understand how they fit together.

The Configuration File

Build configuration in Tauri v2 centers on the tauri.conf.json file inside the src-tauri/ directory. This file is generated when you run tauri init and contains four top-level objects: app, build, bundle, and plugins. The build object is what controls how Tauri locates, builds, and assembles your frontend with the Rust backend.

{
  "productName": "my-tauri-app",
  "version": "0.1.0",
  "build": {
    "beforeBuildCommand": "npm run build",
    "beforeDevCommand": "npm run dev",
    "devUrl": "http://localhost:1420",
    "frontendDist": "../dist"
  },
  "app": {
    "security": {
      "csp": null
    },
    "windows": [
      {
        "title": "My Tauri App",
        "width": 800,
        "height": 600
      }
    ]
  },
  "bundle": {},
  "plugins": {}
}

Four fields inside build control the frontend integration. beforeDevCommand is the shell command Tauri runs when you execute tauri dev — it starts your Vite development server. devUrl tells Tauri where that server is listening so it can point the webview at it. beforeBuildCommand is what runs when you execute tauri build — it compiles your React app into static files. frontendDist tells Tauri where those compiled files land so it can embed them into the final binary.

Tauri also supports platform-specific configuration files that merge with the main config. If you create a tauri.windows.conf.json, tauri.linux.conf.json, or tauri.macos.conf.json alongside the main config, Tauri reads it and overlays its values on top of the base configuration. This lets you set different beforeBuildCommand values or window settings per platform without duplicating the entire file.

The Three Areas of Build Configuration

Each of the three nested pages in this section covers one area in depth. What follows is an overview of what each area addresses, why it matters, and what you should understand before reading the detailed guide.

Preparing for Production

Development and production builds use fundamentally different strategies to serve the frontend. In development, Tauri opens a webview and points it at http://localhost:1420 — your Vite dev server. The frontend code is served from memory, rebuilt on every file change, and never touches the filesystem. This is fast for development but requires Node.js, the Vite binary, and your entire node_modules folder to be present and running.

In production, none of that exists. The frontend must be compiled into static HTML, CSS, and JavaScript files ahead of time, and those files must be physically present on disk so Tauri can embed them into the Rust binary. The beforeBuildCommand field is what bridges this gap. For a React + Vite project, it is typically npm run build, which runs vite build and outputs static files to the dist/ folder. The frontendDist field then points Tauri to that folder.

The distinction between devUrl and frontendDist is worth internalizing early. devUrl is used only during tauri dev and points to a running server. frontendDist is used only during tauri build and points to static files on disk. They serve the same purpose — telling Tauri where the frontend is — but they operate in completely different contexts. Confusing the two is a common source of "works in dev, broken in production" scenarios.

For the full walkthrough of setting up a production-ready build, including handling environment variables, cache busting, and verifying the output, see the Preparing for Production page.

Optimizing Builds

The Rust compiler, by default, optimizes for compile speed during development. It produces binaries with debug symbols, skips aggressive inlining, and compiles each crate independently to allow incremental recompilation. This is exactly what you want when you are iterating — fast cargo build times matter more than binary size.

For a shipping application, the priorities invert. Users care about download size, launch time, and memory usage. They do not care how long the CI pipeline took. Configuring the [profile.release] section in src-tauri/Cargo.toml tells the Rust compiler to spend more time compiling in exchange for a smaller, faster binary.

[profile.release]
codegen-units = 1
lto = "fat"
opt-level = "z"
panic = "abort"
strip = true

Each of these settings trades compile time for output quality. codegen-units = 1 tells the compiler to optimize the entire crate as a single unit, which enables more inlining and dead code elimination but eliminates parallel code generation. lto = "fat" performs link-time optimization across all dependencies, not just your code — the linker can strip unused functions from libraries you depend on. opt-level = "z" prioritizes binary size over speed, which is generally the right tradeoff for desktop apps where download size matters more than microbenchmarks. panic = "abort" removes the panic unwinding machinery, shrinking the binary. strip = true removes debug symbols entirely.

Beyond the Rust compiler, Tauri itself provides a build optimization: the removeUnusedCommands setting in tauri.conf.json. When set to true, Tauri analyzes your frontend code and removes any Rust commands that are never called from JavaScript. This is a tree-shaking pass at the IPC boundary — if you registered a command but never invoke it, it does not ship in the final binary.

The Optimizing Builds page covers these settings in detail, including when opt-level = "s" might be a better choice than "z", how to measure binary size improvements, and the interaction between Tauri's bundler and the Rust compiler optimizations.

Platform Requirements

Every Tauri app embeds a system webview to render the frontend. On Linux, that webview is WebKitGTK. On Windows, it is WebView2. On macOS, it is WKWebView. Each of these requires specific system libraries to be present on the machine that compiles the app — not just the machine that runs it.

For Linux, the critical dependency is webkit2gtk-4.1. Tauri v2 specifically requires the 4.1 version of the library, which uses libsoup3 for HTTP networking. Older distributions that ship only webkit2gtk-4.0 (which uses libsoup2) cannot build Tauri v2 applications natively. This is a deliberate change from Tauri v1 and affects which Linux distributions can serve as build hosts.

sudo apt update
sudo apt install -y libwebkit2gtk-4.1-dev libappindicator3-dev \
  librsvg2-dev patchelf libssl-dev libgtk-3-dev \
  libsoup-3.0-dev libjavascriptcoregtk-4.1-dev

sudo dnf install -y webkit2gtk4.1-devel libappindicator-gtk3-devel \
  librsvg2-devel patchelf openssl-devel gtk3-devel \
  libsoup3-devel javascriptcoregtk4.1-devel

The platform you build on does not have to match the platform you target — cross-compilation is possible for some combinations. Building Windows installers from Linux works using cargo-xwin, which provides the MSVC toolchain without requiring a Windows license. Building for macOS from Linux or Windows is not supported due to Apple's tooling restrictions. The Platform Requirements page covers every supported build host and target combination, including CI runner configurations.

Putting It Together

A typical production build sequence for a Tauri v2 app with a React + Vite frontend looks like this:

npm run build
ls dist/  # should show index.html, assets/, and other static files

{
  "build": {
    "beforeBuildCommand": "npm run build",
    "beforeDevCommand": "npm run dev",
    "devUrl": "http://localhost:1420",
    "frontendDist": "../dist"
  }
}

[profile.release]
codegen-units = 1
lto = "fat"
opt-level = "z"
panic = "abort"
strip = true

npm run tauri build

Summary

Build configuration in Tauri v2 is the set of decisions that turn a project that works on your machine into an application that works on anyone's machine. It spans two ecosystems — JavaScript for the frontend pipeline and Rust for the compiled backend — and it requires awareness of what each target operating system needs from the build host.

The most common failure modes all trace back to one of three root causes: the frontend is not being compiled before Tauri tries to embed it, the Rust compiler is producing unnecessarily large or slow binaries because the release profile was never configured, or the build machine is missing a system library that the target platform requires. Each of these has a straightforward fix once you know what to look for.

The detailed pages that follow — Preparing for Production, Optimizing Builds, and Platform Requirements — walk through each area with concrete configuration examples, troubleshooting guidance, and platform-specific instructions. If you are setting up a project for the first time, work through them in order. If you are debugging a specific build failure, jump directly to the page that matches your symptoms.