$ cat /posts/tauri-20-configuration-tauriconfjson-complete-guide.md

Tauri 2.0 Configuration tauri.conf.json Complete Guide

drwxr-xr-x2026-01-285 min0 views

The tauri.conf.json file is the central configuration hub for your Tauri application, controlling every aspect of your application's behavior including window appearance and properties, build process and development server, security policies with Content Security Policy (CSP), bundle generation for platform-specific installers, allowlist permissions for frontend API access, application metadata like name and version, and platform-specific customizations for Windows, macOS, and Linux. Mastering this configuration file enables you to customize application behavior without code changes, implement security best practices through proper CSP and allowlist configuration, optimize build outputs for production deployment, configure auto-updates for seamless user experience, manage multi-window applications, and create professional installers with proper metadata. This comprehensive guide covers every section of tauri.conf.json with practical examples including build configuration for development and production, application properties and window settings, security policies and capability system (Tauri 2.0), bundle configuration for installers, platform-specific settings, and real-world configuration patterns for common use cases. Whether you're creating your first Tauri app or optimizing an existing application, understanding tauri.conf.json is essential for building secure, performant, and user-friendly desktop applications. The configuration uses JSON format with TypeScript-based validation providing autocomplete and error checking in modern code editors.

Configuration File Location

The configuration file lives at src-tauri/tauri.conf.json in your project root. This location is standard across all Tauri projects. See project structure guide for complete directory organization.

plaintextfile_location.txt

my-tauri-app/
├── src/                      # Frontend code
├── src-tauri/
│   ├── tauri.conf.json       # ← Configuration file here
│   ├── Cargo.toml
│   └── src/
│       └── main.rs
├── package.json
└── vite.config.ts

Basic Configuration Structure

jsonbasic_structure.json

{
  "$schema": "../node_modules/@tauri-apps/cli/schema.json",
  "build": {
    // Build configuration
  },
  "productName": "My Tauri App",
  "version": "0.1.0",
  "identifier": "com.company.app",
  "app": {
    // Application configuration
    "windows": [],
    "security": {},
    "trayIcon": {}
  },
  "bundle": {
    // Bundle configuration for installers
  },
  "plugins": {
    // Plugin configurations
  }
}

Schema Autocomplete: The $schema field provides IntelliSense in VS Code and other editors. You get autocomplete suggestions, inline documentation, and validation as you type. This makes configuration much easier!

Build Configuration

The build section controls development server settings and production build commands. Tauri needs to know how to start your frontend dev server and build production assets.

jsonbuild_configuration.json

{
  "build": {
    // Command to start dev server (npm run tauri dev)
    "beforeDevCommand": "npm run dev",
    
    // Command to build frontend (npm run tauri build)
    "beforeBuildCommand": "npm run build",
    
    // URL where dev server runs
    "devUrl": "http://localhost:1420",
    
    // Directory containing built frontend files
    "frontendDist": "../dist",
    
    // Additional features to enable
    "features": [],
    
    // Whether to run dev command in separate terminal
    "withGlobalTauri": false
  }
}

Framework-Specific Build Commands

Framework	beforeDevCommand	beforeBuildCommand	devUrl
Vite (React/Vue/Svelte)	npm run dev	npm run build	http://localhost:1420
Next.js	npm run dev	npm run build && npm run export	http://localhost:3000
Create React App	npm start	npm run build	http://localhost:3000
Angular	ng serve	ng build --configuration production	http://localhost:4200

Application Metadata

jsonapp_metadata.json

{
  // Application name (shown in window title, installers)
  "productName": "My Awesome App",
  
  // Version number (semver format)
  "version": "1.0.0",
  
  // Unique identifier (reverse domain notation)
  // Used for app data directory, system identification
  "identifier": "com.mycompany.myawesomeapp"
}

// Identifier examples:
// com.company.app          - Standard format
// io.github.username.app   - GitHub projects
// org.opensource.app       - Open source projects

// Version updates:
// 1.0.0 → 1.0.1  (patch: bug fixes)
// 1.0.0 → 1.1.0  (minor: new features)
// 1.0.0 → 2.0.0  (major: breaking changes)

Identifier Importance: The identifier must be unique and should never change after initial release. It determines app data storage location and is used by operating systems to identify your application. Changing it requires users to reinstall.

Window Configuration

The app.windows array defines window properties. You can configure multiple windows, each with unique settings. Learn more about window management.

jsonwindow_configuration.json

{
  "app": {
    "windows": [
      {
        // Window identifier (for programmatic access)
        "label": "main",
        
        // Window title (shown in titlebar)
        "title": "My Awesome App",
        
        // Initial dimensions
        "width": 1000,
        "height": 700,
        
        // Size constraints
        "minWidth": 600,
        "minHeight": 400,
        "maxWidth": 1920,
        "maxHeight": 1080,
        
        // Allow user to resize
        "resizable": true,
        
        // Show maximize button
        "maximizable": true,
        
        // Show minimize button
        "minimizable": true,
        
        // Show close button
        "closable": true,
        
        // Start in fullscreen
        "fullscreen": false,
        
        // Center window on screen
        "center": true,
        
        // Initial position (if not centered)
        "x": null,
        "y": null,
        
        // Show window titlebar and borders
        "decorations": true,
        
        // Always on top of other windows
        "alwaysOnTop": false,
        
        // Transparent window (requires special styling)
        "transparent": false,
        
        // Window is visible on creation
        "visible": true,
        
        // Theme: "light", "dark", or null (system)
        "theme": null,
        
        // Skip taskbar (Windows/Linux)
        "skipTaskbar": false,
        
        // File drop enabled
        "fileDropEnabled": true,
        
        // Content protection (screenshot prevention)
        "contentProtected": false,
        
        // Window title bar style (macOS)
        "titleBarStyle": "Visible",
        
        // Hidden title with transparent titlebar (macOS)
        "hiddenTitle": false,
        
        // Accept first mouse click (macOS)
        "acceptFirstMouse": false,
        
        // Tab handling (macOS)
        "tabbingIdentifier": null,
        
        // User attention request type
        "userAttentionType": null,
        
        // Initial focus
        "focus": true
      }
    ]
  }
}

Multiple Window Configuration

jsonmultiple_windows.json

{
  "app": {
    "windows": [
      {
        "label": "main",
        "title": "Main Window",
        "width": 1000,
        "height": 700,
        "center": true
      },
      {
        "label": "settings",
        "title": "Settings",
        "width": 600,
        "height": 400,
        "center": true,
        "visible": false,  // Hidden until explicitly shown
        "resizable": false
      },
      {
        "label": "splash",
        "title": "",
        "width": 400,
        "height": 300,
        "decorations": false,  // No titlebar
        "transparent": true,
        "alwaysOnTop": true,
        "center": true
      }
    ]
  }
}

// Access windows in Rust:
// let main_window = app.get_window("main").unwrap();
// let settings_window = app.get_window("settings").unwrap();

Security Configuration

Security is critical in desktop applications. Tauri provides Content Security Policy (CSP) and capabilities system for fine-grained permission control. Learn more about security best practices.

jsonsecurity_configuration.json

{
  "app": {
    "security": {
      // Content Security Policy
      "csp": {
        // Default policy for all resources
        "default-src": "'self'",
        
        // JavaScript sources
        "script-src": "'self' 'unsafe-inline'",
        
        // CSS sources
        "style-src": "'self' 'unsafe-inline'",
        
        // Image sources
        "img-src": "'self' data: https:",
        
        // Font sources
        "font-src": "'self' data:",
        
        // Connect sources (HTTP, WebSocket)
        "connect-src": "'self' https://api.example.com",
        
        // Media sources (audio, video)
        "media-src": "'self'",
        
        // Object sources (plugins)
        "object-src": "'none'",
        
        // Frame sources (iframes)
        "frame-src": "'none'",
        
        // Worker sources
        "worker-src": "'self'"
      },
      
      // Freeze the Object prototype
      "freezePrototype": true,
      
      // Enable dangerous remote domain IPC access (not recommended)
      "dangerousRemoteDomainIpcAccess": []
    }
  }
}

// Simplified CSP string format:
{
  "app": {
    "security": {
      "csp": "default-src 'self'; img-src 'self' data: https:; style-src 'self' 'unsafe-inline'"
    }
  }
}

Common CSP Configurations

Use Case	CSP Configuration
Strict (Recommended)	default-src 'self'
With Inline Styles	default-src 'self'; style-src 'self' 'unsafe-inline'
External API Access	default-src 'self'; connect-src 'self' https://api.example.com
External Images	default-src 'self'; img-src 'self' https: data:
CDN Fonts	default-src 'self'; font-src 'self' https://fonts.gstatic.com

Capabilities System (Tauri 2.0)

Tauri 2.0 introduces capabilities—fine-grained permissions for what APIs your frontend can access. Capabilities are defined in separate JSON files in src-tauri/capabilities/ and referenced in configuration.

jsoncapabilities_reference.json

// tauri.conf.json - Reference capabilities
{
  "app": {
    "windows": [
      {
        "label": "main",
        "title": "My App",
        // Reference capability configuration
        "capabilities": ["default", "file-access"]
      }
    ]
  }
}

// src-tauri/capabilities/default.json
{
  "identifier": "default",
  "description": "Default permissions",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "dialog:default"
  ]
}

// src-tauri/capabilities/file-access.json
{
  "identifier": "file-access",
  "description": "File system access",
  "windows": ["main"],
  "permissions": [
    "fs:read-file",
    "fs:write-file",
    "fs:read-dir",
    "fs:create-dir"
  ]
}

Bundle Configuration

The bundle section controls installer generation including platform-specific settings, application icons, and distribution metadata. See build configuration guide and Windows installers.

jsonbundle_configuration.json

{
  "bundle": {
    // Enable bundling
    "active": true,
    
    // Bundle formats: "all", "deb", "appimage", "nsis", "msi", "app", "dmg"
    "targets": "all",
    
    // Bundle identifier (same as app identifier)
    "identifier": "com.mycompany.myapp",
    
    // Publisher name
    "publisher": "My Company",
    
    // Application icons (various sizes)
    "icon": [
      "icons/32x32.png",
      "icons/128x128.png",
      "icons/[email protected]",
      "icons/icon.icns",
      "icons/icon.ico"
    ],
    
    // Application category (macOS/Linux)
    "category": "DeveloperTool",
    
    // Short description (installer, app stores)
    "shortDescription": "An awesome desktop application",
    
    // Long description (detailed info)
    "longDescription": "A comprehensive desktop application built with Tauri 2.0 providing amazing features...",
    
    // Copyright notice
    "copyright": "Copyright © 2026 My Company. All rights reserved.",
    
    // License file
    "licenseFile": "LICENSE",
    
    // External binaries to bundle
    "externalBin": [],
    
    // Resources to include
    "resources": [],
    
    // Create desktop shortcut
    "createDesktopShortcut": true,
    
    // macOS-specific settings
    "macOS": {
      "minimumSystemVersion": "10.13",
      "exceptionDomain": "",
      "signingIdentity": null,
      "providerShortName": null,
      "entitlements": null
    },
    
    // Windows-specific settings
    "windows": {
      "certificateThumbprint": null,
      "digestAlgorithm": "sha256",
      "timestampUrl": "",
      "tsp": false,
      "wix": {
        "language": "en-US"
      },
      "nsis": {
        "installerIcon": "icons/icon.ico",
        "installMode": "perUser",
        "languages": ["English"],
        "displayLanguageSelector": false
      }
    },
    
    // Linux-specific settings
    "linux": {
      "deb": {
        "depends": []
      },
      "appimage": {
        "bundleMediaFramework": false
      }
    }
  }
}

Application Categories

Category	Use For
DeveloperTool	Development tools, IDEs, editors
Utility	System utilities, productivity tools
AudioVideo	Media players, audio/video editors
Graphics	Image editors, design tools
Network	Network tools, browsers, email
Office	Productivity apps, document editors
Education	Learning apps, educational software
Game	Games and entertainment

Auto-Updater Configuration

Configure automatic updates to keep users on the latest version. Learn more about implementing auto-updates.

jsonupdater_configuration.json

{
  "plugins": {
    "updater": {
      // Enable updater
      "active": true,
      
      // Update check endpoints
      "endpoints": [
        "https://github.com/mycompany/myapp/releases/latest/download/latest.json"
      ],
      
      // Dialog configuration
      "dialog": true,
      
      // Public key for signature verification (Tauri 2.0)
      "pubkey": "YOUR_PUBLIC_KEY_HERE",
      
      // Windows-specific updater settings
      "windows": {
        "installMode": "passive"
      }
    }
  }
}

// latest.json format:
{
  "version": "1.1.0",
  "notes": "Bug fixes and improvements",
  "pub_date": "2026-01-27T12:00:00Z",
  "platforms": {
    "windows-x86_64": {
      "signature": "SIGNATURE_HERE",
      "url": "https://github.com/mycompany/myapp/releases/download/v1.1.0/myapp_1.1.0_x64-setup.nsis.zip"
    },
    "darwin-x86_64": {
      "signature": "SIGNATURE_HERE",
      "url": "https://github.com/mycompany/myapp/releases/download/v1.1.0/myapp_1.1.0_x64.app.tar.gz"
    },
    "linux-x86_64": {
      "signature": "SIGNATURE_HERE",
      "url": "https://github.com/mycompany/myapp/releases/download/v1.1.0/myapp_1.1.0_amd64.AppImage.tar.gz"
    }
  }
}

System Tray Configuration

jsontray_configuration.json

{
  "app": {
    "trayIcon": {
      // Icon path (optional, uses app icon if not specified)
      "iconPath": "icons/tray-icon.png",
      
      // Icon size (automatic if null)
      "iconAsTemplate": true,
      
      // Tooltip text
      "tooltip": "My Awesome App",
      
      // Menu items
      "menuOnLeftClick": false
    }
  }
}

// Tray menu defined in Rust code (main.rs):
// use tauri::Manager;
// 
// let tray_menu = tauri::menu::MenuBuilder::new(app)
//     .item(&tauri::menu::MenuItem::new(app, "Show", true, None)?)
//     .separator()
//     .item(&tauri::menu::MenuItem::new(app, "Quit", true, None)?)
//     .build()?;

Complete Configuration Example

jsoncomplete_example.json

{
  "$schema": "../node_modules/@tauri-apps/cli/schema.json",
  "productName": "My Awesome App",
  "version": "1.0.0",
  "identifier": "com.mycompany.myawesomeapp",
  "build": {
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run build",
    "devUrl": "http://localhost:1420",
    "frontendDist": "../dist"
  },
  "app": {
    "windows": [
      {
        "label": "main",
        "title": "My Awesome App",
        "width": 1000,
        "height": 700,
        "minWidth": 600,
        "minHeight": 400,
        "resizable": true,
        "center": true,
        "decorations": true,
        "capabilities": ["default"]
      }
    ],
    "security": {
      "csp": "default-src 'self'; img-src 'self' data: https:; style-src 'self' 'unsafe-inline'"
    },
    "trayIcon": {
      "tooltip": "My Awesome App"
    }
  },
  "bundle": {
    "active": true,
    "targets": "all",
    "identifier": "com.mycompany.myawesomeapp",
    "publisher": "My Company",
    "icon": [
      "icons/32x32.png",
      "icons/128x128.png",
      "icons/[email protected]",
      "icons/icon.icns",
      "icons/icon.ico"
    ],
    "category": "DeveloperTool",
    "shortDescription": "An awesome desktop application",
    "copyright": "Copyright © 2026 My Company",
    "createDesktopShortcut": true,
    "macOS": {
      "minimumSystemVersion": "10.13"
    },
    "windows": {
      "nsis": {
        "installMode": "perUser"
      }
    }
  },
  "plugins": {
    "updater": {
      "active": true,
      "endpoints": [
        "https://github.com/mycompany/myapp/releases/latest/download/latest.json"
      ],
      "dialog": true
    }
  }
}

Configuration Best Practices

Strict CSP: Start with default-src 'self' and only relax for specific needs
Unique Identifier: Use reverse domain notation and never change after release
Semantic Versioning: Follow semver (1.0.0 → 1.0.1 for patches, 1.1.0 for features, 2.0.0 for breaking changes)
Window Constraints: Set reasonable min/max sizes to prevent broken layouts
Bundle Metadata: Provide complete descriptions, copyright, and categories for professional installers
Capabilities: Use fine-grained permissions—only grant access to APIs your app actually needs
Icon Quality: Use high-resolution source images (1024x1024) for best results across platforms
Environment-Specific: Consider different configs for development vs. production (relaxed CSP in dev)
Version Control: Commit tauri.conf.json but exclude sensitive data like signing keys
Schema Validation: Keep $schema field for IntelliSense and validation

Common Configuration Issues

Issue	Cause	Solution
"CSP blocked resource"	Strict CSP preventing load	Add resource origin to appropriate CSP directive
"Window too small/large"	Missing size constraints	Set minWidth, minHeight, maxWidth, maxHeight
"Identifier error"	Invalid format or characters	Use reverse domain notation: com.company.app
"Build fails"	Incorrect frontendDist path	Check path relative to tauri.conf.json location
"Icons missing"	Icon paths incorrect	Verify paths relative to src-tauri/ directory
"Permission denied"	Missing capability	Add required permission to capabilities file

Next Steps

Build Frontend: Integrate React for modern UI development
Implement IPC: Master frontend-backend communication
Manage Windows: Create multiple windows and dialogs
Enhance Security: Deep dive into CSP and permissions
Setup Updates: Implement auto-update system
Optimize Builds: Configure release builds and optimization

Conclusion

The tauri.conf.json file is your application's control center, providing declarative configuration for every aspect of your Tauri application from window appearance to security policies, build processes to platform-specific installers, and auto-updates to system tray integration. Mastering this configuration enables you to customize application behavior without code changes, implement security best practices through proper CSP and capabilities configuration, create professional installers with complete metadata, optimize development workflow with proper build settings, and manage complex multi-window applications effectively. Understanding configuration options including build commands for different frameworks, window properties for various use cases, security policies balancing functionality and protection, bundle settings for professional distribution, and platform-specific customizations for optimal user experience sets the foundation for building production-ready Tauri applications. Continue refining your configuration as your application grows, always prioritizing security with strict CSP and minimal permissions, providing complete metadata for professional presentation, and testing configurations across all target platforms to ensure consistent behavior and appearance.

$ echo $TAGS: #Security #tauri.conf.json #tauri configuration #app metadata #window settings #CSP #allowlist

$ share --platform

[X] TWITTER [in] LINKEDIN [f] FACEBOOK

$ cat /comments/ (0)

new_comment.sh

$ cat /comments/

// No comments found. Be the first!