# How to Configure tauri.conf.json for Different Build and Release Options > Master tauri.conf.json for flexible Tauri app builds. Learn to configure settings for development, debug, and production releases to optimize your application pipeline. - Repository: [Tauri/tauri](https://github.com/tauri-apps/tauri) - Tags: how-to-guide - Published: 2026-02-26 --- **The [`tauri.conf.json`](https://github.com/tauri-apps/tauri/blob/main/tauri.conf.json) file serves as the single source of truth for Tauri application metadata, build pipelines, and bundling output**, enabling distinct configurations for development, debug, and production release modes through the `build` and `bundle` sections. The [`tauri.conf.json`](https://github.com/tauri-apps/tauri/blob/main/tauri.conf.json) file (or its JSON5/TOML equivalents) in the [tauri-apps/tauri](https://github.com/tauri-apps/tauri) repository controls how your application compiles and packages across different environments. It is parsed by the **tauri-cli** during both `tauri dev` and `tauri build` commands, with its structure formally defined by the JSON schema located at [`crates/tauri-schema-generator/schemas/config.schema.json`](https://github.com/tauri-apps/tauri/blob/main/crates/tauri-schema-generator/schemas/config.schema.json). ## Understanding the Core Configuration Structure The configuration file is divided into sections that control different phases of the application lifecycle. According to the schema in [`crates/tauri-schema-generator/schemas/config.schema.json`](https://github.com/tauri-apps/tauri/blob/main/crates/tauri-schema-generator/schemas/config.schema.json), the two primary sections for build-time behavior are: - **`build`**: Controls frontend asset preparation, specifying commands to run before development or building, and defining where the CLI looks for compiled assets. - **`bundle`**: Describes final packaged artifacts, including which installers to generate (`targets`), icon paths, code signing parameters, and platform-specific settings for Windows, macOS, and Linux. ## Development Configuration (`tauri dev`) During development, Tauri launches a web server or uses a static folder while running the Rust side in debug mode. The `build` section defines how the frontend is served during this phase. ```json { "$schema": "../node_modules/@tauri-apps/cli/schema.json", "productName": "My App", "identifier": "com.example.myapp", "version": "0.1.0", "build": { "beforeDevCommand": "npm run dev", "frontendDist": "../dist", "devUrl": "http://localhost:3000" }, "app": { "windows": [ { "title": "My App – Development", "width": 1024, "height": 768 } ] }, "bundle": { "active": false } } ``` **Key development fields:** - **`beforeDevCommand`**: Spawns the frontend dev server (e.g., Vite, Webpack); Tauri waits for it to be reachable at the specified `devUrl`. - **`devUrl`**: The URL where the development server runs, typically `http://localhost:3000` or similar. - **`frontendDist`**: Serves as the fallback asset directory when running without a dev server, but is ignored while `devUrl` is reachable. - **`bundle.active`**: Set to `false` to prevent the CLI from attempting to create installers during `tauri dev`. ## Debug Build Configuration (`tauri build --debug`) Debug builds compile Rust in debug mode but still produce installable bundles for internal testing. This configuration balances fast compile times with packaging validation. ```json { "productName": "My App", "identifier": "com.example.myapp", "version": "0.1.0", "build": { "beforeBuildCommand": "npm run build", "frontendDist": "../dist" }, "bundle": { "active": true, "targets": "all", "icon": [ "icons/32x32.png", "icons/128x128.png", "icons/icon.icns", "icons/icon.ico" ], "windows": { "signCommand": "signtool sign /f test.pfx /p password $PACKAGE_PATH" }, "macOS": { "hardenedRuntime": false } } } ``` **Debug-specific considerations:** - **`beforeBuildCommand`**: Executes a production-grade frontend build (e.g., `npm run build`) before the Rust compilation begins. - **`bundle.active`**: Must be `true` to generate installers (`.exe`, `.dmg`, `.AppImage`, etc.). - **`windows.signCommand`**: Use a self-signed certificate for testing; the schema defines this under the **WindowsConfig** object. - **`macOS.hardenedRuntime`**: Set to `false` during debugging to avoid notarization complexities; the schema at [`config.schema.json`](https://github.com/tauri-apps/tauri/blob/main/config.schema.json) documents this under **MacOSConfig**. ## Production Release Configuration (`tauri build`) Production releases compile Rust in release mode with optimizations enabled, requiring strict security policies and proper code signing for distribution. ```json { "productName": "My App", "identifier": "com.example.myapp", "version": "1.2.3", "build": { "beforeBuildCommand": "npm run build", "frontendDist": "../dist" }, "app": { "windows": [ { "title": "My App", "width": 1280, "height": 800, "transparent": false } ], "security": { "csp": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'" } }, "bundle": { "active": true, "targets": "osx,dmg,msi,deb", "icon": [ "icons/32x32.png", "icons/128x128.png", "icons/icon.icns", "icons/icon.ico" ], "windows": { "signCommand": "signtool sign /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 /f prod.pfx /p password $PACKAGE_PATH", "certificateThumbprint": "ABCD1234...", "timestampUrl": "http://timestamp.digicert.com" }, "macOS": { "hardenedRuntime": true, "signingIdentity": "Developer ID Application: Example Corp", "entitlements": "entitlements.mac.plist", "notarize": true }, "linux": { "deb": { "depends": ["libgtk-3-0", "libwebkit2gtk-4.1-0"], "maintainer": "Jane Doe " } } } } ``` **Production-critical settings:** - **`app.security.csp`**: Must define a strict Content Security Policy; the default `null` value is insecure for released binaries. The schema defines this under **SecurityConfig**. - **`bundle.windows.signCommand`** / **`certificateThumbprint`**: Required for trusted Windows installers; see the **WindowsConfig** definition in the schema around line 130. - **`bundle.macOS.hardenedRuntime`**: Must be `true` for notarization compliance with Apple requirements. - **`bundle.targets`**: Use comma-separated values (e.g., `"osx,dmg,msi"`) to limit output formats rather than building all targets. ## Platform-Specific Configuration Overrides For per-OS tweaks that should not affect other platforms, create files named `tauri..conf.json` (e.g., [`tauri.windows.conf.json`](https://github.com/tauri-apps/tauri/blob/main/tauri.windows.conf.json), [`tauri.linux.conf.json`](https://github.com/tauri-apps/tauri/blob/main/tauri.linux.conf.json)). The CLI automatically merges these **after** the main [`tauri.conf.json`](https://github.com/tauri-apps/tauri/blob/main/tauri.conf.json), with platform files taking precedence. ```json // tauri.windows.conf.json { "app": { "windows": [ { "transparent": true, "titleBarStyle": "Overlay" } ] }, "bundle": { "windows": { "allowDowngrades": false } } } ``` As documented in the schema's top-level description, these platform-specific configuration files enable you to override any top-level key for a specific operating system without polluting the generic configuration. ## Build Mode Comparison Reference | Setting | Development (`tauri dev`) | Debug (`tauri build --debug`) | Release (`tauri build`) | |---------|----------------------------|-------------------------------|-------------------------| | `build.beforeDevCommand` | ✅ Required (runs dev server) | ❌ Ignored | ❌ Ignored | | `build.beforeBuildCommand` | ❌ Ignored | ✅ Required | ✅ Required | | `bundle.active` | `false` (recommended) | `true` | `true` | | `bundle.targets` | Ignored | `all` or subset | Specific list (e.g., `dmg,msi`) | | `bundle.windows.signCommand` | ❌ Skipped | Self-signed (optional) | Real certificate required | | `bundle.macOS.hardenedRuntime` | `false` | `false` | `true` (required for notarization) | | `app.security.csp` | `null` (default) | `null` (debug) | Strict policy required | ## Key Repository Files for Configuration Understanding the source helps validate your configuration: - **[`crates/tauri-schema-generator/schemas/config.schema.json`](https://github.com/tauri-apps/tauri/blob/main/crates/tauri-schema-generator/schemas/config.schema.json)**: The master JSON Schema defining every valid field and type constraint. - **[`crates/tauri-cli/templates/app/src-tauri/tauri.conf.json`](https://github.com/tauri-apps/tauri/blob/main/crates/tauri-cli/templates/app/src-tauri/tauri.conf.json)**: Template used by `tauri init` to bootstrap new projects. - **[`crates/tauri/src/config/mod.rs`](https://github.com/tauri-apps/tauri/blob/main/crates/tauri/src/config/mod.rs)**: Runtime parser that merges configurations and exposes `AppConfig`, `BuildConfig`, and `BundleConfig` structs to the Rust core. ## Practical Configuration Tips - **Validate before building**: Run `tauri schema validate` to catch typos against the official schema. - **Version management**: Point `"version": "package.json"` to automatically sync your Tauri version with your frontend package.json. - **Frontend distribution**: Use `../dist` relative to `src-tauri` for `frontendDist` to maintain clean path resolution across platforms. - **Icon organization**: The `bundle.icon` array accepts paths relative to `src-tauri`; include PNGs for Linux, ICNS for macOS, and ICO for Windows. - **Environment variables**: Reference environment variables in string values using standard shell syntax within command fields. ## Summary - The **[`tauri.conf.json`](https://github.com/tauri-apps/tauri/blob/main/tauri.conf.json)** file in tauri-apps/tauri declaratively bridges your frontend build pipeline and native bundler. - The **`build`** section governs how assets are collected and served during `tauri dev` versus `tauri build`. - The **`bundle`** section controls installer generation, code signing, and platform-specific packaging metadata. - Platform-specific override files (`tauri..conf.json`) allow environment-specific customization without modifying the base configuration. - All configuration fields are formally described in the JSON schema at [`crates/tauri-schema-generator/schemas/config.schema.json`](https://github.com/tauri-apps/tauri/blob/main/crates/tauri-schema-generator/schemas/config.schema.json), enabling IDE autocomplete and validation. ## Frequently Asked Questions ### How do I switch between development and production builds? Use `tauri dev` for development with hot-reloading and `tauri build` for production releases. The CLI automatically selects the appropriate configuration context; ensure `bundle.active` is `false` during development to skip packaging, and `true` for release builds to generate installers. ### Can I use different icons for development and production? Yes. While the `bundle.icon` array is static, you can use platform-specific override files (e.g., [`tauri.windows.conf.json`](https://github.com/tauri-apps/tauri/blob/main/tauri.windows.conf.json)) to define different icon paths for specific platforms, or manage icon sets through your `beforeBuildCommand` script that prepares assets before Tauri bundles them. ### What is the difference between `beforeDevCommand` and `beforeBuildCommand`? The `beforeDevCommand` runs when you execute `tauri dev`, typically starting a Vite or Webpack development server that Tauri connects to via `devUrl`. The `beforeBuildCommand` runs during `tauri build`, executing your production frontend build (e.g., `npm run build`) to generate optimized assets in `frontendDist` before Rust compilation begins. ### How do I configure code signing for Windows and macOS releases? For Windows, set `bundle.windows.signCommand` to your `signtool` invocation or use `certificateThumbprint` for automatic signing. For macOS, set `bundle.macOS.signingIdentity` to your Developer ID, enable `hardenedRuntime`, and set `notarize` to `true` with your Apple ID credentials configured in environment variables. These fields are strictly defined in the **BundleConfig** section of the schema.