Bundle Settings

The bundle configuration tells Tauri how to package your application for distribution. Without it, tauri build compiles your code but does not produce an installer or app bundle that users can actually install. Every setting that controls the final output—which platforms to build for, what extra files to include, what metadata appears in the installer—lives inside the bundle object in tauri.conf.json. You can ship a bare executable without any of this, but that is not how people expect to receive desktop software. The bundle configuration bridges the gap between a compiled Rust binary and a polished, distributable application.

Configuring Bundle Settings Step by Step

The order here is a practical setup flow. You can jump around, but following these steps will get you a working bundle configuration quickly.

{
  "bundle": {
    "active": true
  }
}

{
  "bundle": {
    "active": true,
    "targets": ["app", "dmg", "updater"]
  }
}

{
  "bundle": {
    "active": true,
    "targets": "all",
    "icon": [
      "icons/icon.png",
      "icons/icon.ico"
    ]
  }
}

{
  "bundle": {
    "resources": [
      "assets/*.json",
      "data/templates/"
    ]
  }
}

{
  "bundle": {
    "copyright": "© 2024 My Company",
    "category": "Developer Tool",
    "shortDescription": "A tiny task manager",
    "longDescription": "A lightweight desktop task manager built with Tauri and React."
  }
}

Now that the big pieces are in place, the following sections explain each setting in detail and cover the options that do not appear in the step‑by‑step flow.

Activating Bundling with active

The active field is a simple boolean. When true, the Tauri CLI passes your configuration to the bundler after compiling your app. When false, the bundler is completely skipped.

{
  "bundle": {
    "active": true
  }
}

There is no deeper mechanism here—it is a master switch. Use it during development when you want to compile quickly without waiting for installer packaging, then turn it on for release builds.

Choosing Bundle Targets

The targets field accepts either the string "all" or an array of specific target identifiers. The bundler will only produce targets that make sense on the current operating system, so you can safely list all desired formats in a single configuration file and let the build machine pick the applicable ones.

{
  "bundle": {
    "active": true,
    "targets": ["app", "dmg", "nsis", "deb", "appimage", "updater"]
  }
}

What you observe when you build: on a macOS machine, only app, dmg, and updater artifacts will appear in src-tauri/target/release/bundle/. The deb and appimage targets are silently ignored because the bundler knows they cannot be produced there. This is the intended behaviour—you can commit one config and run CI on multiple operating systems without adjusting the target list per platform.

Adding Resources to the Bundle

The resources field tells the bundler to include extra files or folders inside the final application package. This is useful for assets that your frontend build step does not know about: a pre‑populated database, a default configuration file, or a directory of downloadable templates.

{
  "bundle": {
    "resources": [
      "assets/legal/*.pdf",
      "default_config.json"
    ]
  }
}

Paths are relative to the src-tauri directory. Globs are expanded at build time, so assets/legal/*.pdf will include every PDF found in that folder when tauri build runs. The bundled resources end up in the platform‑specific resource directory—for example, MyApp.app/Contents/Resources/ on macOS. From the frontend, you reference them as tauri://localhost/assets/legal/privacy.pdf. In Rust, you can resolve them with app.path().resource_dir().

Including External Binaries (Sidecars)

When your application needs to launch an external executable—a CLI tool, a helper server, a database process—the externalBin field tells the bundler to package that binary alongside your app. This is not the same as resources; sidecars are executables that you will spawn from Rust using tauri::api::process::Command or std::process::Command.

{
  "bundle": {
    "externalBin": [
      "binaries/my-helper"
    ]
  }
}

The file path is relative to src-tauri and should not include a platform‑specific extension. Tauri will automatically append .exe on Windows. The bundled binary ends up next to your main executable, and you can locate it at runtime through app.path().resource_dir().

This feature is explored with full examples in the External Binaries (Sidecars) chapter.

Application Metadata Fields

The copyright, category, shortDescription, and longDescription fields populate visible text in installers and in the operating system’s application launcher. They are all optional, but omitting them makes your app look unpolished.

• copyright — A string displayed in the installer and (on macOS) in the Finder’s “Get Info” panel.
• category — A human‑readable category name that Tauri translates to platform‑specific codes. For example, "Developer Tool" becomes public.app-category.developer-tools on macOS and Development in a .desktop file on Linux.
• shortDescription — A one‑line summary, typically shown in the Windows Add/Remove Programs list.
• longDescription — A longer description, used by package managers like dpkg or shown in the Microsoft Store.

{
  "bundle": {
    "copyright": "© 2024 Acme Corp.",
    "category": "Utility",
    "shortDescription": "A clipboard manager for power users.",
    "longDescription": "ClipVault captures everything you copy and lets you search, organize, and sync your clipboard history across devices."
  }
}

If you do not provide these, the generated installers will fall back to defaults or empty placeholders. That does not block installation, but it looks sloppy to end users.

Generating Updater Artifacts

When createUpdaterArtifacts is set to true, Tauri generates the metadata files needed by the Tauri updater plugin. This is a separate toggle from the updater target in the targets list—targets controls whether the actual update packages are built; createUpdaterArtifacts controls whether the manifest and signature files are produced.

{
  "bundle": {
    "createUpdaterArtifacts": true
  }
}

If you plan to use the updater plugin later, turn this on now. There is no harm in having it enabled even if you do not use updates yet; the extra files are small and sit alongside the bundles.

Using Local Build Tools

The useLocalToolsDir flag is for situations where you cannot or do not want Tauri to download bundler tooling (WiX, NSIS, create-dmg) from the internet during the build. When true, Tauri expects the required tools to be installed in a local directory, typically ~/.cargo/tauri/tools or a location set via the TAURI_TOOLS_DIR environment variable.

{
  "bundle": {
    "useLocalToolsDir": true
  }
}

This is most useful in air‑gapped build environments, corporate networks with strict firewall rules, or when you need a specific version of WiX that differs from the one Tauri would fetch automatically. If you set this to true and the tools are missing, the build will fail with a clear error telling you which tool is needed.

The Bundle Identifier

Although identifier lives at the root of the Tauri configuration, not inside the bundle object, it is the single most important value that determines how the operating system identifies your application. Every bundle format uses it: the macOS CFBundleIdentifier, the Windows GUID, the Android application ID, and the Linux desktop file name.

{
  "identifier": "com.mycompany.myapp"
}

The value must be in reverse‑domain notation and unique across all applications on a user’s system. If two installed apps share the same identifier, the operating system will confuse their data directories, settings, and uninstall entries—often silently corrupting one or both.

Application Category in Detail

The category field accepts a free‑form string, but it is best to use one of the values recognised by the target platforms. Tauri maps it automatically, but the mapping works only when the input string is one it knows.

Common values and their platform‑specific representations:

A Complete Bundle Configuration Example

The following snippet puts together all the settings discussed in this document. This is a realistic configuration for a productivity application targeting macOS, Windows, and Linux, with updater support enabled.

{
  "productName": "ClipVault",
  "version": "1.0.0",
  "identifier": "com.acme.clipvault",
  "bundle": {
    "active": true,
    "targets": ["app", "dmg", "nsis", "deb", "appimage", "updater"],
    "icon": [
      "icons/32x32.png",
      "icons/128x128.png",
      "icons/128x128@2x.png",
      "icons/icon.icns",
      "icons/icon.ico"
    ],
    "resources": [
      "assets/templates/*.hbs",
      "assets/defaults.json"
    ],
    "copyright": "© 2024 Acme Corp.",
    "category": "Utilities",
    "shortDescription": "A clipboard manager for power users.",
    "longDescription": "ClipVault captures everything you copy and lets you search, organize, and sync your clipboard history across devices.",
    "createUpdaterArtifacts": true,
    "useLocalToolsDir": false,
    "externalBin": [
      "binaries/clip-sync-helper"
    ]
  }
}

When you run tauri build with this configuration and the required platform tooling is available, the bundler will produce:

• On macOS: ClipVault.app inside a ClipVault_1.0.0_x64.dmg, plus updater manifest and signature files.
• On Windows: a ClipVault_1.0.0_x64-setup.exe NSIS installer, plus updater artifacts.
• On Linux: a .deb package, an AppImage, and updater artifacts.

The externalBin binary clip-sync-helper (or clip-sync-helper.exe on Windows) will be placed alongside the main executable in every bundle.

Summary

Bundle settings turn a compiled Tauri binary into something users can install and run without technical knowledge. The process is driven by a handful of fields: active as the master switch, targets to declare desired formats, resources and externalBin to ship extra data, and metadata fields to fill in the text that appears in installer dialogs. Every field outside the platform‑specific sub‑objects (macOS, windows, linux) is operating‑system‑agnostic, so you can write one configuration that works everywhere. The biggest pitfalls are forgetting to set active: true and choosing an identifier that you cannot change later without splitting your user base.