tauri-core-config

name	tauri-core-config
description	Use when editing tauri.conf.json, configuring build options, or setting up platform-specific bundle configuration. Prevents invalid configuration keys and v1 config patterns that silently fail in Tauri 2. Covers build settings, app settings, window configuration, bundle options, plugin configuration, and security settings. Keywords: tauri.conf.json, configuration, build settings, bundle options, window config, security settings.
license	MIT
compatibility	Designed for Claude Code. Requires Tauri 2.x with Rust and TypeScript.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

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/[e-mail]",
        "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/[e-mail]",
            "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/