Application Configuration

The app configuration object is where you define how your Tauri application behaves at runtime. It controls the windows it creates, the security rules that protect your users, which APIs are available to your frontend, and a handful of OS-specific knobs. If the top-level fields like productName and identifier describe what your app is, the app object describes what it does while it is running.

This page focuses solely on the app section of tauri.conf.json. The top-level metadata (productName, version, identifier) is covered in Product Configuration, and the build object is covered in Build Configuration.

The Structure of the App Object

A minimal app object looks like this:

{
  "app": {
    "windows": [],
    "security": {
      "capabilities": [],
      "assetProtocol": {
        "enable": false,
        "scope": []
      },
      "freezePrototype": false,
      "pattern": {
        "use": "brownfield"
      }
    },
    "withGlobalTauri": false,
    "enableGTKAppId": false,
    "macOSPrivateApi": false
  }
}

Every property is optional, and Tauri falls back to sensible defaults when you omit them. The rest of this page explains what each property does and when you would change it.

Configuring Application Windows

The windows array tells Tauri which windows to create when your app launches. Each entry is a window configuration object.

{
  "app": {
    "windows": [
      {
        "title": "My Tauri App",
        "width": 1024,
        "height": 720,
        "resizable": true
      }
    ]
  }
}

If the array is empty, Tauri still opens a single window with default settings. Adding entries lets you set the title, size, decorations, and behavior of each window. Window configuration is rich enough that it deserves its own chapter — see Window Configuration for everything from positioning to always-on-top behavior.

Security Settings

The security object controls what your frontend code is allowed to do and how Tauri isolates it. This is the most important section of the app configuration for keeping your users safe — see Security & Capabilities. Every setting has a default that errs on the side of restriction.

Capabilities

Capabilities are the modern, fine-grained permission system in Tauri v2. The capabilities array lists capability identifiers that grant access to specific APIs. You define capabilities in separate files inside src-tauri/capabilities/, and you reference them here to activate them for your app.

{
  "app": {
    "security": {
      "capabilities": ["default"]
    }
  }
}

This tells Tauri to load the capability defined in src-tauri/capabilities/default.json. A typical capability file grants permissions for window manipulation, path access, and core APIs. If you omit the capabilities field, your frontend will have no Tauri API access at all — button clicks that call invoke or window.__TAURI__ will silently do nothing.

Content Security Policy (CSP)

The csp field accepts a Content Security Policy string that restricts where your frontend can load resources from. If you set it to null, Tauri disables CSP entirely.

{
  "app": {
    "security": {
      "csp": "default-src 'self'; script-src 'self' 'unsafe-inline'"
    }
  }
}

This policy allows scripts only from the same origin and inline scripts. If you need to load images from a remote CDN, you would add img-src 'self' https://cdn.example.com. Tauri applies this CSP to the webview that hosts your frontend. When csp is null, the webview has no restrictions, which is sometimes useful during development but should be tightened before distribution.

Asset Protocol Scope

The assetProtocol object controls whether Tauri’s custom asset protocol is enabled and which paths it can serve. When enabled, your frontend can reference files using the asset:// scheme.

{
  "app": {
    "security": {
      "assetProtocol": {
        "enable": true,
        "scope": ["**"]
      }
    }
  }
}

The scope uses glob patterns. "**" allows access to any file inside the app’s resource directories. You can restrict it to a specific folder, for example ["images/*"], to limit what the frontend can request. If you are not serving local assets to your frontend through custom protocols, leave this disabled.

Freezing the Prototype

The freezePrototype option prevents your frontend JavaScript from modifying built-in prototypes like Object.prototype or Array.prototype. It is false by default.

{
  "app": {
    "security": {
      "freezePrototype": true
    }
  }
}

Enabling this hardens your app against certain supply-chain attacks — a malicious dependency that tries to tamper with prototypes will find them frozen. The tradeoff is that some older JavaScript libraries that rely on prototype modification will break. If all your dependencies are modern, turning this on is a good security practice.

Pattern — Brownfield vs. Isolation

The pattern object tells Tauri what security model to apply to the webview. The use field accepts "brownfield" (default) or "isolation".

{
  "app": {
    "security": {
      "pattern": {
        "use": "brownfield"
      }
    }
  }
}

In brownfield mode, the Tauri APIs are injected directly into the frontend’s JavaScript context. This is the easiest to work with but means your frontend runs with full access to the Tauri runtime. In isolation mode, Tauri creates a separate hidden iframe that holds the Tauri API, and your frontend communicates with it through message passing. Isolation prevents malicious frontend code (for example, from an XSS vulnerability) from directly calling native APIs. For most projects, brownfield is fine; for applications that handle sensitive data or load untrusted content, isolation is the safer choice.

Exposing the Global Tauri API

The withGlobalTauri option, when set to true, makes the Tauri API available on the global window.__TAURI__ object. When false, the API is only available through the @tauri-apps/api package’s imports.

{
  "app": {
    "withGlobalTauri": false
  }
}

Leaving this false is the recommended approach. It keeps your frontend code explicit — you import what you need — and tree-shaking can remove unused API modules from your bundle. The global object is a convenience for quick prototypes or for projects that do not use a module bundler. If you are using React with Vite, stick with false and import from @tauri-apps/api as usual.

Platform-Specific Settings

Two boolean flags let you tweak behavior on Linux and macOS without touching the platform-specific configuration files.

enableGTKAppId

On Linux systems that use GTK, setting enableGTKAppId to true causes Tauri to set the GTK application ID to your app’s identifier. This is required for some desktop integrations — for instance, the system might group windows by application ID in the taskbar. If your app’s windows appear as separate applications on Linux, enabling this often resolves the issue.

{
  "app": {
    "enableGTKAppId": true
  }
}

macOSPrivateApi

Setting macOSPrivateApi to true enables two macOS-specific behaviors: it allows you to use the transparent background API (so your window can have a completely see-through background), and it sets the fullScreenEnabled preference to true. This flag is necessary if you want to render windows with rounded corners that blend into the desktop or build a widget-style app. It uses private macOS APIs, which means it might break with future macOS updates and should be tested thoroughly before distribution.

{
  "app": {
    "macOSPrivateApi": true
  }
}

Common Configuration Mistakes

The most frequent errors around the app configuration come from mixing Tauri v1 and v2 syntax. If you are migrating an older project, watch for these specifically.

Putting package or tauri keys in the root of the config file. These were top-level keys in Tauri v1. In v2, the root keys are productName, version, identifier, build, app, bundle, and plugins. A stray "package": {} will produce an error like Additional properties are not allowed ('package' was unexpected).

Using v1 build fields like devPath and distDir instead of devUrl and frontendDist. The build configuration changed entirely in v2. If you see errors about unexpected properties on the build object, check that you are using the correct field names.

Placing bundle inside app. The bundle object is a top-level configuration, not a child of app. This mistake is common because both relate to the application output. A misplaced bundle inside app will cause a validation error.

Missing or misnamed capability files. If you list "default" in the capabilities array but there is no src-tauri/capabilities/default.json, Tauri will not warn you during build — your app will simply launch with no API access. The frontend will fail at runtime with opaque errors.

The app configuration is where your Tauri project goes from "it compiles" to "it behaves correctly." The defaults are safe and cover the common case, but understanding each knob lets you lock down security, fine-tune window behavior, and adapt your app to the quirks of each operating system.