tauri-core-config · v1.0 · 2026-03-18 · sha256 5c502b065f4e0fd3
tauri-core-config v1.0A
Immutable. This exact content is served forever at /api/v1/blob/5c502b065f4e0fd3.
---
name: tauri-core-config
description: "Guides tauri.conf.json configuration including build settings, app settings, window configuration, bundle options, plugin configuration, and security settings. Activates when editing tauri.conf.json, configuring Tauri build options, or setting up platform-specific bundle configuration."
license: MIT
compatibility: "Designed for Claude Code. Requires Tauri 2.x with Rust and TypeScript."
metadata:
author: Impertio
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:
```json
{
"$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:
```json
{
"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:
```json
{
"icon": [
"icons/32x32.png",
"icons/128x128.png",
"icons/128x128@2x.png",
"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:
```json
{
"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:
```json
{
"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/128x128@2x.png",
"icons/icon.icns",
"icons/icon.ico"
]
}
}
```
---
## Reference Links
- [references/methods.md](references/methods.md) -- Complete tauri.conf.json schema reference with all properties
- [references/examples.md](references/examples.md) -- Config examples: minimal, full, platform-specific
- [references/anti-patterns.md](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/