OpenAEC-Foundation/tauri-core-config

tauri-core-config

Quick Reference

Configuration File Location

The main configuration file lives at src-tauri/tauri.conf.json. Tauri auto-generates JSON schemas in src-tauri/gen/schemas/ for IDE autocompletion.

Top-Level Keys

| Key | Type | Required | Description | |-----|------|----------|-------------| | $schema | string | No | Path to JSON schema for IDE validation | | identifier | string | Yes | Reverse domain notation (e.g., com.example.myapp) | | productName | string \| null | No | Display name of the application | | version | string \| null | No | Semver version or path to package.json | | mainBinaryName | string \| null | No | Override the compiled binary filename | | build | object | No | Build configuration | | app | object | No | Application runtime configuration | | bundle | object | No | Bundling and distribution configuration | | plugins | object | No | Per-plugin configuration (default: {}) |

Schema Reference

ALWAYS include the $schema key for IDE autocompletion and validation:

{
    "$schema": "./gen/schemas/desktop-schema.json"
}

Available schemas (auto-generated in src-tauri/gen/schemas/):

• desktop-schema.json -- desktop platform configuration
• mobile-schema.json -- mobile platform configuration
• remote-schema.json -- remote URL capabilities

Critical Warnings

NEVER omit the identifier field -- it is the ONLY required field. It MUST be unique reverse-domain notation (com.example.myapp). Using a non-unique identifier causes conflicts with other apps on the system.

NEVER use build.devUrl without build.beforeDevCommand -- the dev server will not start automatically, causing Tauri to connect to nothing.

NEVER omit build.beforeBuildCommand -- frontend assets will not be compiled before bundling, producing an app with missing or stale UI.

NEVER set app.security.csp to null in production -- this disables all Content Security Policy restrictions, leaving the app vulnerable to XSS attacks.

NEVER set app.security.dangerousDisableAssetCspModification to true unless you fully understand CSP nonce injection.

NEVER edit files in gen/schemas/ -- they are auto-generated and will be overwritten on the next build.

---

Build Section

The build section controls how the frontend is compiled and served during development and production.

| Property | Type | Default | Description | |----------|------|---------|-------------| | devUrl | string \| null | null | Dev server URL (e.g., http://localhost:5173) | | frontendDist | string \| array | -- | Path to compiled frontend assets (e.g., ../dist) | | beforeDevCommand | string \| object | -- | Shell command before tauri dev | | beforeBuildCommand | string \| object | -- | Shell command before tauri build | | beforeBundleCommand | string \| object | -- | Shell command before the bundling phase | | features | string[] \| null | null | Cargo feature flags to enable | | additionalWatchFolders | string[] | [] | Extra paths to watch during tauri dev | | removeUnusedCommands | boolean | false | Remove unused commands during build based on ACL config |

Command Object Form

beforeDevCommand, beforeBuildCommand, and beforeBundleCommand support an object form:

{
    "beforeDevCommand": {
        "script": "npm run dev",
        "cwd": "../frontend",
        "wait": false
    }
}

| Property | Type | Description | |----------|------|-------------| | script | string | The shell command to run | | cwd | string | Working directory (relative to project root) | | wait | boolean | Wait for the command to finish before continuing |

Build Rules

• ALWAYS pair devUrl with beforeDevCommand -- the dev server must be running before Tauri connects
• ALWAYS set frontendDist to the output directory of your frontend build tool
• ALWAYS set beforeBuildCommand to compile frontend assets for production
• frontendDist is relative to src-tauri/, so ../dist points to project-root/dist

---

App Section

The app section configures runtime behavior including windows, security, and platform-specific features.

| Property | Type | Default | Description | |----------|------|---------|-------------| | windows | WindowConfig[] | [] | Windows created at startup | | security | object | -- | Security settings | | trayIcon | TrayIconConfig \| null | null | System tray icon configuration | | withGlobalTauri | boolean | false | Inject Tauri API on window.__TAURI__ | | enableGTKAppId | boolean | false | Set identifier as GTK app ID (Linux) | | macOSPrivateApi | boolean | false | Enable transparent background + fullscreen (macOS) |

Window Configuration (app.windows[])

| Property | Type | Default | Description | |----------|------|---------|-------------| | label | string | "main" | Unique window identifier | | title | string | -- | Window title bar text | | url | string | "/" | URL or path to load | | width | number | -- | Width in logical pixels | | height | number | -- | Height in logical pixels | | x / y | number | -- | Window position | | minWidth / minHeight | number | -- | Minimum dimensions | | maxWidth / maxHeight | number | -- | Maximum dimensions | | resizable | boolean | true | Allow resizing | | fullscreen | boolean | false | Start fullscreen | | focus | boolean | true | Focus on creation | | create | boolean | true | Create at startup | | transparent | boolean | false | Enable window transparency | | decorations | boolean | true | Show title bar / borders | | alwaysOnTop | boolean | false | Stay above other windows |

Window Rules

• ALWAYS set a unique label for each window -- labels are used for IPC targeting and window lookup
• Set create: false for windows you want to create programmatically from Rust
• The url property accepts relative paths (/settings.html) or custom protocol URLs
• Use minWidth/minHeight to prevent the window from being resized too small

Security Section (app.security)

| Property | Type | Default | Description | |----------|------|---------|-------------| | csp | string \| object \| null | null | Content Security Policy | | capabilities | string[] | [] | Explicit capability file paths (overrides auto-discovery) | | freezePrototype | boolean | false | Freeze JavaScript Object.prototype | | dangerousDisableAssetCspModification | boolean \| string[] | false | Disable automatic CSP nonce injection | | assetProtocol.enable | boolean | false | Enable the asset:// protocol | | assetProtocol.scope | string[] | [] | Allowed paths for asset:// | | pattern.use | string | "brownfield" | Application pattern ("brownfield" or "isolation") |

Security Rules

• ALWAYS enable freezePrototype in production -- it prevents prototype pollution attacks
• ALWAYS define a restrictive CSP in production -- never leave it as null
• Use the isolation pattern for maximum security (adds an isolation layer between frontend and IPC)
• When specifying capabilities explicitly, auto-discovery of src-tauri/capabilities/ is disabled

---

Bundle Section

The bundle section controls application packaging and distribution.

| Property | Type | Default | Description | |----------|------|---------|-------------| | active | boolean | true | Enable/disable bundling | | targets | string \| string[] | "all" | Target platforms/formats | | icon | string[] | -- | Icon file paths (all required sizes) | | resources | object | {} | Additional files/directories to bundle | | externalBin | string[] | [] | External binaries to embed as sidecars | | fileAssociations | array | [] | File type associations | | category | string | -- | App category (e.g., "Utility") | | copyright | string | -- | Copyright notice | | publisher | string | -- | Publisher name | | license | string | -- | SPDX license identifier | | licenseFile | string | -- | Path to license file | | createUpdaterArtifacts | boolean \| "v1Compatible" | false | Generate update signatures |

Required Icon Sizes

ALWAYS include all required icon formats:

{
    "icon": [
        "icons/32x32.png",
        "icons/128x128.png",
        "icons/[email protected]",
        "icons/icon.icns",
        "icons/icon.ico"
    ]
}

Use tauri icon CLI command to generate all sizes from a single source image.

Platform-Specific Bundle Configuration

Windows (bundle.windows)

| Property | Type | Description | |----------|------|-------------| | nsis | object | NSIS installer configuration | | wix | object | WiX (MSI) configuration | | webviewInstallMode | string | "downloadBootstrapper" or "offlineInstallerFromUrl" | | signCommand | string | Custom signing command (%1 = file path) | | certificateThumbprint | string \| null | Certificate thumbprint for Authenticode | | digestAlgorithm | string | Hash algorithm (typically "sha256") | | timestampUrl | string | Timestamp server URL | | allowDowngrades | boolean | Permit version downgrades |

macOS (bundle.macOS)

| Property | Type | Description | |----------|------|-------------| | dmg | object | DMG configuration (window size, positions) | | hardenedRuntime | boolean | Enable hardened runtime (default: true) | | minimumSystemVersion | string | Minimum macOS version (default: "10.13") | | signingIdentity | string \| null | Code signing identity |

Linux (bundle.linux)

| Property | Type | Description | |----------|------|-------------| | deb | object | Debian package config | | rpm | object | RPM package config | | appimage | object | AppImage config | | appimage.bundleMediaFramework | boolean | Bundle media framework (default: false) |

iOS (bundle.iOS)

| Property | Type | Description | |----------|------|-------------| | minimumSystemVersion | string | Default: "14.0" |

Android (bundle.android)

| Property | Type | Description | |----------|------|-------------| | minSdkVersion | number | Default: 24 | | versionCode | number | Auto-calculated from semver | | autoIncrementVersionCode | boolean | Increment on each build |

Updater Rules

• ALWAYS set TAURI_SIGNING_PRIVATE_KEY environment variable before enabling createUpdaterArtifacts
• Use true for new projects, "v1Compatible" ONLY when migrating from Tauri v1 updater
• NEVER lose the updater private key -- it makes pushing updates to existing installations impossible

---

Plugins Section

The plugins section provides per-plugin configuration as key-value pairs:

{
    "plugins": {
        "fs": {
            "scope": {
                "allow": ["$APPDATA/**", "$HOME/Documents/**"],
                "deny": ["$HOME/.ssh/**"]
            }
        },
        "http": {
            "scope": {
                "allow": ["https://api.example.com/*"]
            }
        }
    }
}

Plugin configuration keys match the plugin name without the tauri-plugin- prefix.

---

Minimal Viable Config

The absolute minimum tauri.conf.json that works:

{
    "identifier": "com.example.myapp",
    "build": {
        "devUrl": "http://localhost:5173",
        "frontendDist": "../dist",
        "beforeDevCommand": "npm run dev",
        "beforeBuildCommand": "npm run build"
    },
    "app": {
        "windows": [
            {
                "title": "My App",
                "width": 800,
                "height": 600
            }
        ]
    },
    "bundle": {
        "active": true,
        "icon": [
            "icons/32x32.png",
            "icons/128x128.png",
            "icons/[email protected]",
            "icons/icon.icns",
            "icons/icon.ico"
        ]
    }
}

---

Reference Links

• references/methods.md -- Complete tauri.conf.json schema reference with all properties
• references/examples.md -- Config examples: minimal, full, platform-specific
• references/anti-patterns.md -- Common config mistakes and how to avoid them

Official Sources

• https://v2.tauri.app/reference/config/
• https://v2.tauri.app/develop/configuration/
• https://v2.tauri.app/distribute/