Bundle Configuration

The bundle section of your tauri.conf.json is where you tell Tauri how to package your finished application into installers that users can actually run on their operating system. Without bundling, you have a working binary but no .dmg, .exe, .deb, or any other familiar installer format—just raw files that are difficult to distribute.

This section controls which package formats are produced, which icons are embedded into those packages, how platform-specific installers behave, and which file types your app can open when a user double-clicks a document. It does not control the frontend build—that lives in the build section—but it does control everything that happens after both your React frontend and your Rust backend have been compiled. The Building & Distribution chapter covers how these settings turn into shipped installers.

Bundle Settings

The top-level properties of the bundle object govern the overall bundling behavior. Open src-tauri/tauri.conf.json and look for the bundle key. A minimal, working bundle configuration looks like this:

{
  "bundle": {
    "active": true,
    "targets": ["app", "dmg"],
    "icon": [
      "icons/32x32.png",
      "icons/128x128.png",
      "icons/128x128@2x.png",
      "icons/icon.icns",
      "icons/icon.ico"
    ]
  }
}

active

A boolean that enables or disables the entire bundling step. When set to false, tauri build will still compile your Rust code but will skip producing any platform-specific packages. This is occasionally useful during development when you only want to check that compilation succeeds without waiting for packaging.

targets

Specifies which installer formats the bundler should produce. You can use the string "all" (the default) to build every format appropriate for the current operating system, or provide an array of specific targets.

The available targets depend on the platform you are building on:

The "app" target creates the bare application bundle without an installer wrapper. On macOS it produces a .app folder; on Windows it produces a directory containing the .exe and its dependencies. The installer targets (dmg, nsis, deb, etc.) wrap that application bundle into a familiar installer format.

createUpdaterArtifacts

When set to true, Tauri will generate additional archive files (.app.tar.gz on macOS, .msi.zip on Windows, .AppImage.tar.gz on Linux) that the built-in updater plugin can use. This is only relevant if you are implementing an auto-update system. If you are not using the updater, leave this as false (the default) to keep your output directory clean.

useLocalToolsDir

A niche setting. When true, Tauri looks for bundling tools (like wix or nsis) in a local tools directory next to your src-tauri folder instead of downloading them on demand. Unless you are in an environment with no internet access during builds, you can ignore this flag.

Application Icons

The icon array tells the bundler which icon files to embed into your application binary and installer. The icons directory in src-tauri is the usual place to keep them. Every platform uses a different icon format, and some platforms need multiple sizes. Tauri expects you to provide all of them upfront so the bundler can pick the right one for each target.

The minimum recommended set for a Tauri v2 application:

icons/
  32x32.png
  128x128.png
  128x128@2x.png
  icon.icns
  icon.ico

• 32x32.png – small icon used in system trays and taskbars.
• 128x128.png – standard icon for most desktop environments.
• 128x128@2x.png – high-DPI variant (256x256 pixels actual size) for Retina and HiDPI displays.
• icon.icns – required on macOS. This is a container format that holds multiple resolutions.
• icon.ico – required on Windows. Must include at least a 256x256 version for modern scaling.

All paths are relative to the src-tauri directory (where your tauri.conf.json lives). You can keep icons in a subfolder like icons/ or at any other path—just make sure the paths in the icon array match.

Installer Configuration

Each platform has its own sub-object inside bundle where you can fine-tune the behavior of the installer, set minimum OS versions, and configure code signing. These settings only affect the platform they belong to—configuring macOS does nothing on a Windows build and vice versa.

{
  "bundle": {
    "macOS": {
      "minimumSystemVersion": "11.0",
      "hardenedRuntime": true,
      "signingIdentity": "Developer ID Application: Your Name (TEAMID)",
      "entitlements": "./Entitlements.plist",
      "dmg": {
        "appPosition": { "x": 180, "y": 170 },
        "applicationFolderPosition": { "x": 480, "y": 170 },
        "windowSize": { "height": 400, "width": 660 }
      }
    }
  }
}

File Associations

When users double-click a file, the operating system decides which application to open it with based on the file's extension. Defining file associations in your bundle configuration tells Windows, macOS, and Linux that your app is capable of handling specific file types.

The fileAssociations array inside bundle accepts one or more objects, each describing a file type your app can open.

{
  "bundle": {
    "fileAssociations": [
      {
        "ext": "mydoc",
        "name": "MyApp Document",
        "description": "A document created by MyApp",
        "role": "Editor",
        "mimeType": "application/x-myapp-doc"
      },
      {
        "ext": "mydata",
        "name": "MyApp Data File",
        "description": "A data file for MyApp",
        "role": "Viewer"
      }
    ]
  }
}

Each association object supports these fields:

• ext (required) – The file extension without a leading dot. Use "mydoc", not ".mydoc".
• name (required) – A short human-readable name for the file type. Appears in the file's property dialog on some systems.
• description – A longer description shown in file type registration dialogs (Windows) or Info.plist (macOS). Optional but recommended for clarity.
• role – How your app relates to the file type. Common values are "Editor" (your app can create and modify these files), "Viewer" (your app can display but not edit), and "Shell" (reserved for system use). Defaults to "Editor" if omitted.
• mimeType – The MIME type string for the file format, e.g., "application/x-myapp-doc". Helps browsers and email clients identify the file. Optional but improves cross-platform compatibility.

On macOS, these associations are written into the app's Info.plist under CFBundleDocumentTypes. On Windows, they are written into the registry by the NSIS or WiX installer. On Linux, they are included in the .desktop entry and MIME database files placed inside the package.

Tauri also exposes a way to read the file path that triggered the app launch. In your Rust code, you can access the associated file via tauri::RunEvent::Opened { urls } in the app builder, or through the frontend using @tauri-apps/plugin-deep-link or the single-instance plugin—but that handling belongs to the runtime side, not the bundle configuration itself.

A properly configured bundle section is the difference between a build artifact sitting in a target/release folder and a polished installer that users can download, install, and trust. Icons make your app recognizable; installer settings control the first impression; file associations weave your app into the user's workflow.

The configuration you write here will directly shape what that build produces, so revisit these settings whenever you change your app's name, version, icon, or supported file types.