How to Configure tauri.conf.json for Different Build and Release Options

The 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 file (or its JSON5/TOML equivalents) in the 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.

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, 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.

{
  "$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.

{
  "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 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.

{
  "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 <jane@example.com>"
      }
    }
  }
}

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.<platform>.conf.json (e.g., tauri.windows.conf.json, tauri.linux.conf.json). The CLI automatically merges these after the main tauri.conf.json, with platform files taking precedence.

// 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: The master JSON Schema defining every valid field and type constraint.
• 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: 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 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.<os>.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, 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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}