Configuration
The Tauri configuration object. It is read from a file where you can define your frontend assets, configure the bundler and define a tray icon.
The configuration file is generated by the
tauri init
command that lives in
your Tauri application source directory (src-tauri).
Once generated, you may modify it at will to customize your Tauri application.
File Formats
By default, the configuration is defined as a JSON file named tauri.conf.json
.
Tauri also supports JSON5 and TOML files via the config-json5
and config-toml
Cargo features, respectively.
The JSON5 file name must be either tauri.conf.json
or tauri.conf.json5
.
The TOML file name is Tauri.toml
.
Platform-Specific Configuration
In addition to the default configuration file, Tauri can
read a platform-specific configuration from tauri.linux.conf.json
,
tauri.windows.conf.json
, tauri.macos.conf.json
, tauri.android.conf.json
and tauri.ios.conf.json
(or Tauri.linux.toml
, Tauri.windows.toml
, Tauri.macos.toml
, Tauri.android.toml
and Tauri.ios.toml
if the Tauri.toml
format is used),
which gets merged with the main configuration object.
Configuration Structure
The configuration is composed of the following objects:
app
: The Tauri configurationbuild
: The build configurationbundle
: The bundle configurationsplugins
: The plugins configuration
Example tauri.config.json file:
Object Properties:
- app
- build
- bundle
- identifier (required)
- mainBinaryName
- plugins
- productName
- version
app
The App configuration.
build
The build configuration.
Default: {}
bundle
The bundler configuration.
identifier
string
The application identifier in reverse domain name notation (e.g. com.tauri.example
).
This string must be unique across applications since it is used in system configurations like
the bundle ID and path to the webview data directory.
This string must contain only alphanumeric characters (A-Z, a-z, and 0-9), hyphens (-),
and periods (.).
mainBinaryName
string
| null
App main binary filename. Defaults to the name of your cargo crate.
plugins
The plugins config.
Default: {}
productName
string
| null
pattern of ^[^/\:*?"<>|]+$
App name.
version
string
| null
App version. It is a semver version number or a path to a package.json
file containing the version
field. If removed the version number from Cargo.toml
is used.
By default version 1.0 is used on Android.
Definitions
AndroidConfig
General configuration for the iOS target.
Object Properties:
- minSdkVersion
- versionCode
minSdkVersion
integer
formatted as uint32
The minimum API level required for the application to run. The Android system will prevent the user from installing the application if the system’s API level is lower than the value specified.
Default: 24
versionCode
integer
| null
maximum of 2100000000
, minimum of 1
, formatted as uint32
The version code of the application. It is limited to 2,100,000,000 as per Google Play Store requirements.
By default we use your configured version and perform the following math: versionCode = version.major * 1000000 + version.minor * 1000 + version.patch
AppConfig
The App configuration object.
See more: <https://v2.tauri.app/reference/config/#appconfig>
Object Properties:
- enableGTKAppId
- macOSPrivateApi
- security
- trayIcon
- windows
- withGlobalTauri
enableGTKAppId
boolean
If set to true “identifier” will be set as GTK app ID (on systems that use GTK).
macOSPrivateApi
boolean
MacOS private API configuration. Enables the transparent background API and sets the fullScreenEnabled
preference to true
.
security
Security configuration.
trayIcon
TrayIconConfig
| null
Configuration for app tray icon.
windows
The app windows configuration.
Default: []
withGlobalTauri
boolean
Whether we should inject the Tauri API on window.__TAURI__
or not.
AppImageConfig
Configuration for AppImage bundles.
See more: <https://v2.tauri.app/reference/config/#appimageconfig>
Object Properties:
- bundleMediaFramework
- files
bundleMediaFramework
boolean
Include additional gstreamer dependencies needed for audio and video playback. This increases the bundle size by ~15-35MB depending on your build system.
files
The files to include in the Appimage Binary.
Allows additional properties: string
Default: {}
AssetProtocolConfig
Config for the asset custom protocol.
See more: <https://v2.tauri.app/reference/config/#assetprotocolconfig>
Object Properties:
- enable
- scope
enable
boolean
Enables the asset protocol.
scope
The access scope for the asset protocol.
Default: []
AssociationExt
string
An extension for a [FileAssociation
].
A leading .
is automatically stripped.
BeforeDevCommand
Any of the following:
string
Run the given script with the default options.- Run the given script with custom options. Object Properties: - cwd - script (required) - wait ##### cwd
string
|null
The current working directory. ##### scriptstring
The script to execute. ##### waitboolean
Whethertauri dev
should wait for the command to finish or not. Defaults tofalse
.
Describes the shell command to run before tauri dev
.
BuildConfig
The Build configuration object.
See more: <https://v2.tauri.app/reference/config/#buildconfig>
Object Properties:
- beforeBuildCommand
- beforeBundleCommand
- beforeDevCommand
- devUrl
- features
- frontendDist
- runner
beforeBuildCommand
HookCommand
| null
A shell command to run before tauri build
kicks in.
The TAURI_ENV_PLATFORM, TAURI_ENV_ARCH, TAURI_ENV_FAMILY, TAURI_ENV_PLATFORM_VERSION, TAURI_ENV_PLATFORM_TYPE and TAURI_ENV_DEBUG environment variables are set if you perform conditional compilation.
beforeBundleCommand
HookCommand
| null
A shell command to run before the bundling phase in tauri build
kicks in.
The TAURI_ENV_PLATFORM, TAURI_ENV_ARCH, TAURI_ENV_FAMILY, TAURI_ENV_PLATFORM_VERSION, TAURI_ENV_PLATFORM_TYPE and TAURI_ENV_DEBUG environment variables are set if you perform conditional compilation.
beforeDevCommand
BeforeDevCommand
| null
A shell command to run before tauri dev
kicks in.
The TAURI_ENV_PLATFORM, TAURI_ENV_ARCH, TAURI_ENV_FAMILY, TAURI_ENV_PLATFORM_VERSION, TAURI_ENV_PLATFORM_TYPE and TAURI_ENV_DEBUG environment variables are set if you perform conditional compilation.
devUrl
string
| null
formatted as uri
The URL to load in development.
This is usually an URL to a dev server, which serves your application assets with hot-reload and HMR. Most modern JavaScript bundlers like vite provides a way to start a dev server by default.
If you don’t have a dev server or don’t want to use one, ignore this option and use frontendDist
and point to a web assets directory, and Tauri CLI will run its built-in dev server and provide a simple hot-reload experience.
features
string
[] | null
Features passed to cargo
commands.
frontendDist
FrontendDist
| null
The path to the application assets (usually the dist
folder of your javascript bundler)
or a URL that could be either a custom protocol registered in the tauri app (for example: myprotocol://
)
or a remote URL (for example: https://site.com/app
).
When a path relative to the configuration file is provided,
it is read recursively and all files are embedded in the application binary.
Tauri then looks for an index.html
and serves it as the default entry point for your application.
You can also provide a list of paths to be embedded, which allows granular control over what files are added to the binary. In this case, all files are added to the root and you must reference it that way in your HTML files.
When a URL is provided, the application won’t have bundled assets and the application will load that URL by default.
runner
string
| null
The binary used to build and run the application.
BundleConfig
Configuration for tauri-bundler.
See more: <https://v2.tauri.app/reference/config/#bundleconfig>
Object Properties:
- active
- android
- category
- copyright
- createUpdaterArtifacts
- externalBin
- fileAssociations
- homepage
- icon
- iOS
- license
- licenseFile
- linux
- longDescription
- macOS
- publisher
- resources
- shortDescription
- targets
- useLocalToolsDir
- windows
active
boolean
Whether Tauri should bundle your application or just output the executable.
android
Android configuration.
category
string
| null
The application kind.
Should be one of the following: Business, DeveloperTool, Education, Entertainment, Finance, Game, ActionGame, AdventureGame, ArcadeGame, BoardGame, CardGame, CasinoGame, DiceGame, EducationalGame, FamilyGame, KidsGame, MusicGame, PuzzleGame, RacingGame, RolePlayingGame, SimulationGame, SportsGame, StrategyGame, TriviaGame, WordGame, GraphicsAndDesign, HealthcareAndFitness, Lifestyle, Medical, Music, News, Photography, Productivity, Reference, SocialNetworking, Sports, Travel, Utility, Video, Weather.
copyright
string
| null
A copyright string associated with your application.
createUpdaterArtifacts
Produce updaters and their signatures or not
externalBin
string
[] | null
A list of—either absolute or relative—paths to binaries to embed with your application.
Note that Tauri will look for system-specific binaries following the pattern “binary-name{-target-triple}{.system-extension}“.
E.g. for the external binary “my-binary”, Tauri looks for:
- “my-binary-x86_64-pc-windows-msvc.exe” for Windows
- “my-binary-x86_64-apple-darwin” for macOS
- “my-binary-x86_64-unknown-linux-gnu” for Linux
so don’t forget to provide binaries for all targeted platforms.
fileAssociations
FileAssociation
[] | null
File associations to application.
homepage
string
| null
A url to the home page of your application. If unset, will
fallback to homepage
defined in Cargo.toml
.
Supported bundle targets: deb
, rpm
, nsis
and msi
.
icon
string
[]
The app’s icons
Default: []
iOS
iOS configuration.
license
string
| null
The package’s license identifier to be included in the appropriate bundles. If not set, defaults to the license from the Cargo.toml file.
licenseFile
string
| null
The path to the license file to be included in the appropriate bundles.
linux
Configuration for the Linux bundles.
longDescription
string
| null
A longer, multi-line description of the application.
macOS
Configuration for the macOS bundles.
publisher
string
| null
The application’s publisher. Defaults to the second element in the identifier string.
Currently maps to the Manufacturer property of the Windows Installer and the Maintainer field of debian packages if the Cargo.toml does not have the authors field.
resources
BundleResources
| null
App resources to bundle. Each resource is a path to a file or directory. Glob patterns are supported.
shortDescription
string
| null
A short description of your application.
targets
The bundle targets, currently supports [“deb”, “rpm”, “appimage”, “nsis”, “msi”, “app”, “dmg”] or “all”.
Default: "all"
useLocalToolsDir
boolean
Whether to use the project’s target
directory, for caching build tools (e.g., Wix and NSIS) when building this application. Defaults to false
.
If true, tools will be cached in target\.tauri-tools
.
If false, tools will be cached in the current user’s platform-specific cache directory.
An example where it can be appropriate to set this to true
is when building this application as a Windows System user (e.g., AWS EC2 workloads),
because the Window system’s app data directory is restricted.
windows
Configuration for the Windows bundles.
BundleResources
Any of the following:
string
[] A list of paths to include.- A map of source to target paths. Allows additional properties:
string
Definition for bundle resources. Can be either a list of paths to include or a map of source to target paths.
BundleTarget
Any of the following:
"all"
Bundle all targets.BundleType
[] A list of bundle targets.BundleType
A single bundle target.
Targets to bundle. Each value is case insensitive.
BundleType
One of the following:
"deb"
The debian bundle (.deb)."rpm"
The RPM bundle (.rpm)."appimage"
The AppImage bundle (.appimage)."msi"
The Microsoft Installer bundle (.msi)."nsis"
The NSIS bundle (.exe)."app"
The macOS application bundle (.app)."dmg"
The Apple Disk Image bundle (.dmg).
A bundle referenced by tauri-bundler.
BundleTypeRole
One of the following:
"Editor"
CFBundleTypeRole.Editor. Files can be read and edited."Viewer"
CFBundleTypeRole.Viewer. Files can be read."Shell"
CFBundleTypeRole.Shell"QLGenerator"
CFBundleTypeRole.QLGenerator"None"
CFBundleTypeRole.None
macOS-only. Corresponds to CFBundleTypeRole
Capability
A grouping and boundary mechanism developers can use to isolate access to the IPC layer.
It controls application windows fine grained access to the Tauri core, application, or plugin commands. If a window is not matching any capability then it has no access to the IPC layer at all.
This can be done to create groups of windows, based on their required system access, which can reduce
impact of frontend vulnerabilities in less privileged windows.
Windows can be added to a capability by exact name (e.g. main-window
) or glob patterns like *
or admin-*
.
A Window can have none, one, or multiple associated capabilities.
Example
Object Properties:
- description
- identifier (required)
- local
- permissions (required)
- platforms
- remote
- webviews
- windows
description
string
Description of what the capability is intended to allow on associated windows.
It should contain a description of what the grouped permissions should allow.
Example
This capability allows the main
window access to filesystem
write related
commands and dialog
commands to enable programatic access to files selected by the user.
identifier
string
Identifier of the capability.
Example
main-user-files-write
local
boolean
Whether this capability is enabled for local app URLs or not. Defaults to true
.
Default: true
permissions
PermissionEntry
[] each item must be unique
List of permissions attached to this capability.
Must include the plugin name as prefix in the form of ${plugin-name}:${permission-name}
.
For commands directly implemented in the application itself only ${permission-name}
is required.
Example
platforms
Target
[] | null
Limit which target platforms this capability applies to.
By default all platforms are targeted.
Example
["macOS","windows"]
remote
CapabilityRemote
| null
Configure remote URLs that can use the capability permissions.
This setting is optional and defaults to not being set, as our default use case is that the content is served from our local application.
Example
webviews
string
[]
List of webviews that are affected by this capability. Can be a glob pattern.
This is only required when using on multiwebview contexts, by default
all child webviews of a window that matches [Self::windows
] are linked.
Example
["sub-webview-one", "sub-webview-two"]
windows
string
[]
List of windows that are affected by this capability. Can be a glob pattern.
On multiwebview windows, prefer [Self::webviews
] for a fine grained access control.
Example
["main"]
CapabilityEntry
Any of the following:
Capability
An inlined capability.string
Reference to a capability identifier.
A capability entry which can be either an inlined capability or a reference to a capability defined on its own file.
CapabilityRemote
Configuration for remote URLs that are associated with the capability.
Object Properties:
- urls (required)
urls
string
[]
Remote domains this capability refers to using the URLPattern standard.
Examples
- “https://*.mydomain.dev”: allows subdomains of mydomain.dev
- “https://mydomain.dev/api/*”: allows any subpath of mydomain.dev/api
Color
integer
formatted as uint8
| integer
formatted as uint8
| integer
formatted as uint8
| integer
formatted as uint8
[] maximum of 4
items, minimum of 4
items
a tuple struct of RGBA colors. Each value has minimum of 0 and maximum of 255.
Csp
Any of the following:
string
The entire CSP policy in a single text string.- An object mapping a directive with its sources values as a list of strings. Allows additional properties:
CspDirectiveSources
A Content-Security-Policy definition. See <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>.
CspDirectiveSources
Any of the following:
string
An inline list of CSP sources. Same as [Self::List
], but concatenated with a space separator.string
[] A list of CSP sources. The collection will be concatenated with a space separator for the CSP string.
A Content-Security-Policy directive source list. See <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#sources>.
CustomSignCommandConfig
Any of the following:
string
A string notation of the script to execute. “%1” will be replaced with the path to the binary to be signed. This is a simpler notation for the command. Tauri will split the string with' '
and use the first element as the command name and the rest as arguments. If you need to use whitespace in the command or arguments, use the object notation [Self::ScriptWithOptions
].- An object notation of the command. This is more complex notation for the command but this allows you to use whitespace in the command and arguments. Object Properties: - args (required) - cmd (required) ##### args
string
[] The arguments to pass to the command. “%1” will be replaced with the path to the binary to be signed. ##### cmdstring
The command to run to sign the binary.
Custom Signing Command configuration.
DebConfig
Configuration for Debian (.deb) bundles.
See more: <https://v2.tauri.app/reference/config/#debconfig>
Object Properties:
- changelog
- conflicts
- depends
- desktopTemplate
- files
- postInstallScript
- postRemoveScript
- preInstallScript
- preRemoveScript
- priority
- provides
- replaces
- section
changelog
string
| null
Path of the uncompressed Changelog file, to be stored at /usr/share/doc/package-name/changelog.gz. See <https://www.debian.org/doc/debian-policy/ch-docs.html#changelog-files-and-release-notes>
conflicts
string
[] | null
The list of package conflicts.
depends
string
[] | null
The list of deb dependencies your application relies on.
desktopTemplate
string
| null
Path to a custom desktop file Handlebars template.
Available variables: categories
, comment
(optional), exec
, icon
and name
.
files
The files to include on the package.
Allows additional properties: string
Default: {}
postInstallScript
string
| null
Path to script that will be executed after the package is unpacked. See <https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html>
postRemoveScript
string
| null
Path to script that will be executed after the package is removed. See <https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html>
preInstallScript
string
| null
Path to script that will be executed before the package is unpacked. See <https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html>
preRemoveScript
string
| null
Path to script that will be executed before the package is removed. See <https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html>
priority
string
| null
Change the priority of the Debian Package. By default, it is set to optional
.
Recognized Priorities as of now are : required
, important
, standard
, optional
, extra
provides
string
[] | null
The list of dependencies the package provides.
replaces
string
[] | null
The list of package replaces.
section
string
| null
Define the section in Debian Control file. See : https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections
DisabledCspModificationKind
Any of the following:
boolean
Iftrue
, disables all CSP modification.false
is the default value and it configures Tauri to control the CSP.string
[] Disables the given list of CSP directives modifications.
The possible values for the dangerous_disable_asset_csp_modification
config option.
DmgConfig
Configuration for Apple Disk Image (.dmg) bundles.
See more: <https://v2.tauri.app/reference/config/#dmgconfig>
Object Properties:
- applicationFolderPosition
- appPosition
- background
- windowPosition
- windowSize
applicationFolderPosition
Position of application folder on window.
appPosition
Position of app file on window.
background
string
| null
Image to use as the background in dmg file. Accepted formats: png
/jpg
/gif
.
windowPosition
Position
| null
Position of volume window on screen.
windowSize
Size of volume window.
FileAssociation
File association
Object Properties:
- description
- ext (required)
- mimeType
- name
- role
description
string
| null
The association description. Windows-only. It is displayed on the Type
column on Windows Explorer.
ext
File extensions to associate with this app. e.g. ‘png’
mimeType
string
| null
The mime-type e.g. ‘image/png’ or ‘text/plain’. Linux-only.
name
string
| null
The name. Maps to CFBundleTypeName
on macOS. Default to ext[0]
role
The app’s role with respect to the type. Maps to CFBundleTypeRole
on macOS.
Default: "Editor"
FrontendDist
Any of the following:
string
formatted asuri
An external URL that should be used as the default application URL.string
Path to a directory containing the frontend dist assets.string
[] An array of files to embed on the app.
Defines the URL or assets to embed in the application.
FsScope
Any of the following:
string
[] A list of paths that are allowed by this scope.- A complete scope configuration. Object Properties: - allow - deny - requireLiteralLeadingDot ##### allow
string
[] A list of paths that are allowed by this scope. Default:[]
##### denystring
[] A list of paths that are not allowed by this scope. This gets precedence over the [Self::Scope::allow
] list. Default:[]
##### requireLiteralLeadingDotboolean
|null
Whether or not paths that contain components that start with a.
will require that.
appears literally in the pattern;*
,?
,**
, or[...]
will not match. This is useful because such files are conventionally considered hidden on Unix systems and it might be desirable to skip them when listing files. Defaults totrue
on Unix systems andfalse
on Windows
Protocol scope definition. It is a list of glob patterns that restrict the API access from the webview.
Each pattern can start with a variable that resolves to a system base directory.
The variables are: $AUDIO
, $CACHE
, $CONFIG
, $DATA
, $LOCALDATA
, $DESKTOP
,
$DOCUMENT
, $DOWNLOAD
, $EXE
, $FONT
, $HOME
, $PICTURE
, $PUBLIC
, $RUNTIME
,
$TEMPLATE
, $VIDEO
, $RESOURCE
, $APP
, $LOG
, $TEMP
, $APPCONFIG
, $APPDATA
,
$APPLOCALDATA
, $APPCACHE
, $APPLOG
.
HookCommand
Any of the following:
string
Run the given script with the default options.- Run the given script with custom options. Object Properties: - cwd - script (required) ##### cwd
string
|null
The current working directory. ##### scriptstring
The script to execute.
Describes a shell command to be executed when a CLI hook is triggered.
Identifier
string
IosConfig
General configuration for the iOS target.
Object Properties:
- developmentTeam
- frameworks
- minimumSystemVersion
- template
developmentTeam
string
| null
The development team. This value is required for iOS development because code signing is enforced.
The APPLE_DEVELOPMENT_TEAM
environment variable can be set to overwrite it.
frameworks
string
[] | null
A list of strings indicating any iOS frameworks that need to be bundled with the application.
Note that you need to recreate the iOS project for the changes to be applied.
minimumSystemVersion
string
A version string indicating the minimum iOS version that the bundled application supports. Defaults to 13.0
.
Maps to the IPHONEOS_DEPLOYMENT_TARGET value.
Default: "13.0"
template
string
| null
A custom XcodeGen project.yml template to use.
LinuxConfig
Configuration for Linux bundles.
See more: <https://v2.tauri.app/reference/config/#linuxconfig>
Object Properties:
- appimage
- deb
- rpm
appimage
Configuration for the AppImage bundle.
deb
Configuration for the Debian bundle.
rpm
Configuration for the RPM bundle.
MacConfig
Configuration for the macOS bundles.
See more: <https://v2.tauri.app/reference/config/#macconfig>
Object Properties:
- dmg
- entitlements
- exceptionDomain
- files
- frameworks
- hardenedRuntime
- minimumSystemVersion
- providerShortName
- signingIdentity
dmg
DMG-specific settings.
entitlements
string
| null
Path to the entitlements file.
exceptionDomain
string
| null
Allows your application to communicate with the outside world. It should be a lowercase, without port and protocol domain name.
files
The files to include in the application relative to the Contents directory.
Allows additional properties: string
Default: {}
frameworks
string
[] | null
A list of strings indicating any macOS X frameworks that need to be bundled with the application.
If a name is used, “.framework” must be omitted and it will look for standard install locations. You may also use a path to a specific framework.
hardenedRuntime
boolean
Whether the codesign should enable hardened runtime (for executables) or not.
Default: true
minimumSystemVersion
string
| null
A version string indicating the minimum macOS X version that the bundled application supports. Defaults to 10.13
.
Setting it to null
completely removes the LSMinimumSystemVersion
field on the bundle’s Info.plist
and the MACOSX_DEPLOYMENT_TARGET
environment variable.
An empty string is considered an invalid value so the default value is used.
Default: "10.13"
providerShortName
string
| null
Provider short name for notarization.
signingIdentity
string
| null
Identity to use for code signing.
NsisCompression
One of the following:
"zlib"
ZLIB uses the deflate algorithm, it is a quick and simple method. With the default compression level it uses about 300 KB of memory."bzip2"
BZIP2 usually gives better compression ratios than ZLIB, but it is a bit slower and uses more memory. With the default compression level it uses about 4 MB of memory."lzma"
LZMA (default) is a new compression method that gives very good compression ratios. The decompression speed is high (10-20 MB/s on a 2 GHz CPU), the compression speed is lower. The memory size that will be used for decompression is the dictionary size plus a few KBs, the default is 8 MB."none"
Disable compression
Compression algorithms used in the NSIS installer.
See <https://nsis.sourceforge.io/Reference/SetCompressor>
NsisConfig
Configuration for the Installer bundle using NSIS.
Object Properties:
- compression
- customLanguageFiles
- displayLanguageSelector
- headerImage
- installerHooks
- installerIcon
- installMode
- languages
- minimumWebview2Version
- sidebarImage
- startMenuFolder
- template
compression
Set the compression algorithm used to compress files in the installer.
See <https://nsis.sourceforge.io/Reference/SetCompressor>
Default: "lzma"
customLanguageFiles
| null
A key-value pair where the key is the language and the
value is the path to a custom .nsh
file that holds the translated text for tauri’s custom messages.
See <https://github.com/tauri-apps/tauri/blob/dev/crates/tauri-bundler/src/bundle/windows/nsis/languages/English.nsh> for an example .nsh
file.
Note: the key must be a valid NSIS language and it must be added to [NsisConfig
] languages array,
Allows additional properties: string
displayLanguageSelector
boolean
Whether to display a language selector dialog before the installer and uninstaller windows are rendered or not.
By default the OS language is selected, with a fallback to the first language in the languages
array.
headerImage
string
| null
The path to a bitmap file to display on the header of installers pages.
The recommended dimensions are 150px x 57px.
installerHooks
string
| null
A path to a .nsh
file that contains special NSIS macros to be hooked into the
main installer.nsi script.
Supported hooks are:
NSIS_HOOK_PREINSTALL
: This hook runs before copying files, setting registry key values and creating shortcuts.NSIS_HOOK_POSTINSTALL
: This hook runs after the installer has finished copying all files, setting the registry keys and created shortcuts.NSIS_HOOK_PREUNINSTALL
: This hook runs before removing any files, registry keys and shortcuts.NSIS_HOOK_POSTUNINSTALL
: This hook runs after files, registry keys and shortcuts have been removed.
Example
installerIcon
string
| null
The path to an icon file used as the installer icon.
installMode
Whether the installation will be for all users or just the current user.
Default: "currentUser"
languages
string
[] | null
A list of installer languages.
By default the OS language is used. If the OS language is not in the list of languages, the first language will be used.
To allow the user to select the language, set display_language_selector
to true
.
See <https://github.com/kichik/nsis/tree/9465c08046f00ccb6eda985abbdbf52c275c6c4d/Contrib/Language%20files> for the complete list of languages.
minimumWebview2Version
string
| null
Try to ensure that the WebView2 version is equal to or newer than this version, if the user’s WebView2 is older than this version, the installer will try to trigger a WebView2 update.
sidebarImage
string
| null
The path to a bitmap file for the Welcome page and the Finish page.
The recommended dimensions are 164px x 314px.
startMenuFolder
string
| null
Set the folder name for the start menu shortcut.
Use this option if you have multiple apps and wish to group their shortcuts under one folder or if you generally prefer to set your shortcut inside a folder.
Examples:
AwesomePublisher
, shortcut will be placed in%AppData%\Microsoft\Windows\Start Menu\Programs\AwesomePublisher\<your-app>.lnk
- If unset, shortcut will be placed in
%AppData%\Microsoft\Windows\Start Menu\Programs\<your-app>.lnk
template
string
| null
A custom .nsi template to use.
NSISInstallerMode
One of the following:
"currentUser"
Default mode for the installer. Install the app by default in a directory that doesn’t require Administrator access. Installer metadata will be saved under theHKCU
registry path."perMachine"
Install the app by default in theProgram Files
folder directory requires Administrator access for the installation. Installer metadata will be saved under theHKLM
registry path."both"
Combines both modes and allows the user to choose at install time whether to install for the current user or per machine. Note that this mode will require Administrator access even if the user wants to install it for the current user only. Installer metadata will be saved under theHKLM
orHKCU
registry path based on the user’s choice.
Install Modes for the NSIS installer.
Number
Any of the following:
integer
formatted asint64
Represents an [i64
].number
formatted asdouble
Represents a [f64
].
A valid ACL number.
PatternKind
One of the following:
- Brownfield pattern. Object Properties: - use (required) ##### use
"brownfield"
- Isolation pattern. Recommended for security purposes. Object Properties: - options (required) - use (required) ##### options Object Properties: - dir (required) ###### dir
string
The dir containing the index.html file that contains the secure isolation application. ##### use"isolation"
The application pattern.
PermissionEntry
Any of the following:
Identifier
Reference a permission or permission set by identifier.- Reference a permission or permission set by identifier and extends its scope. Object Properties: - allow - deny - identifier (required) ##### allow
Value
[] |null
Data that defines what is allowed by the scope. ##### denyValue
[] |null
Data that defines what is denied by the scope. This should be prioritized by validation logic. ##### identifierIdentifier
Identifier of the permission or permission set.
An entry for a permission value in a [Capability
] can be either a raw permission [Identifier
]
or an object that references a permission and extends its scope.
PluginConfig
The plugin configs holds a HashMap mapping a plugin name to its configuration object.
See more: <https://v2.tauri.app/reference/config/#pluginconfig>
Allows additional properties: true
Position
Position coordinates struct.
Object Properties:
- x (required)
- y (required)
x
integer
formatted as uint32
X coordinate.
y
integer
formatted as uint32
Y coordinate.
RpmConfig
Configuration for RPM bundles.
Object Properties:
- conflicts
- depends
- desktopTemplate
- epoch
- files
- obsoletes
- postInstallScript
- postRemoveScript
- preInstallScript
- preRemoveScript
- provides
- release
conflicts
string
[] | null
The list of RPM dependencies your application conflicts with. They must not be present in order for the package to be installed.
depends
string
[] | null
The list of RPM dependencies your application relies on.
desktopTemplate
string
| null
Path to a custom desktop file Handlebars template.
Available variables: categories
, comment
(optional), exec
, icon
and name
.
epoch
integer
formatted as uint32
The RPM epoch.
files
The files to include on the package.
Allows additional properties: string
Default: {}
obsoletes
string
[] | null
The list of RPM dependencies your application supersedes - if this package is installed, packages listed as “obsoletes” will be automatically removed (if they are present).
postInstallScript
string
| null
Path to script that will be executed after the package is unpacked. See <http://ftp.rpm.org/max-rpm/s1-rpm-inside-scripts.html>
postRemoveScript
string
| null
Path to script that will be executed after the package is removed. See <http://ftp.rpm.org/max-rpm/s1-rpm-inside-scripts.html>
preInstallScript
string
| null
Path to script that will be executed before the package is unpacked. See <http://ftp.rpm.org/max-rpm/s1-rpm-inside-scripts.html>
preRemoveScript
string
| null
Path to script that will be executed before the package is removed. See <http://ftp.rpm.org/max-rpm/s1-rpm-inside-scripts.html>
provides
string
[] | null
The list of RPM dependencies your application provides.
release
string
The RPM release tag.
Default: "1"
SecurityConfig
Security configuration.
See more: <https://v2.tauri.app/reference/config/#securityconfig>
Object Properties:
- assetProtocol
- capabilities
- csp
- dangerousDisableAssetCspModification
- devCsp
- freezePrototype
- pattern
assetProtocol
Custom protocol config.
capabilities
List of capabilities that are enabled on the application.
If the list is empty, all capabilities are included.
Default: []
csp
Csp
| null
The Content Security Policy that will be injected on all HTML files on the built application.
If dev_csp
is not specified, this value is also injected on dev.
This is a really important part of the configuration since it helps you ensure your WebView is secured. See <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>.
dangerousDisableAssetCspModification
Disables the Tauri-injected CSP sources.
At compile time, Tauri parses all the frontend assets and changes the Content-Security-Policy to only allow loading of your own scripts and styles by injecting nonce and hash sources. This stricts your CSP, which may introduce issues when using along with other flexing sources.
This configuration option allows both a boolean and a list of strings as value. A boolean instructs Tauri to disable the injection for all CSP injections, and a list of strings indicates the CSP directives that Tauri cannot inject.
WARNING: Only disable this if you know what you are doing and have properly configured the CSP. Your application might be vulnerable to XSS attacks without this Tauri protection.
devCsp
Csp
| null
The Content Security Policy that will be injected on all HTML files on development.
This is a really important part of the configuration since it helps you ensure your WebView is secured. See <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>.
freezePrototype
boolean
Freeze the Object.prototype
when using the custom protocol.
pattern
The pattern to use.
Size
Size of the window.
Object Properties:
- height (required)
- width (required)
height
integer
formatted as uint32
Height of the window.
width
integer
formatted as uint32
Width of the window.
Target
One of the following:
"macOS"
MacOS."windows"
Windows."linux"
Linux."android"
Android."iOS"
iOS.
Platform target.
Theme
One of the following:
"Light"
Light theme."Dark"
Dark theme.
System theme.
TitleBarStyle
One of the following:
"Visible"
A normal title bar."Transparent"
Makes the title bar transparent, so the window background color is shown instead. Useful if you don’t need to have actual HTML under the title bar. This lets you avoid the caveats of usingTitleBarStyle::Overlay
. Will be more useful when Tauri lets you set a custom window background color."Overlay"
Shows the title bar as a transparent overlay over the window’s content. Keep in mind: - The height of the title bar is different on different OS versions, which can lead to window the controls and title not being where you don’t expect. - You need to define a custom drag region to make your window draggable, however due to a limitation you can’t drag the window when it’s not in focus <https://github.com/tauri-apps/tauri/issues/4316>. - The color of the window title depends on the system theme.
How the window title bar should be displayed on macOS.
TrayIconConfig
Configuration for application tray icon.
See more: <https://v2.tauri.app/reference/config/#trayiconconfig>
Object Properties:
- iconAsTemplate
- iconPath (required)
- id
- menuOnLeftClick
- title
- tooltip
iconAsTemplate
boolean
A Boolean value that determines whether the image represents a template image on macOS.
iconPath
string
Path to the default icon to use for the tray icon.
Note: this stores the image in raw pixels to the final binary, so keep the icon size (width and height) small or else it’s going to bloat your final executable
id
string
| null
Set an id for this tray icon so you can reference it later, defaults to main
.
menuOnLeftClick
boolean
A Boolean value that determines whether the menu should appear when the tray icon receives a left click on macOS.
Default: true
title
string
| null
Title for MacOS tray
tooltip
string
| null
Tray icon tooltip on Windows and macOS
Updater
Any of the following:
V1Compatible
Generates lagacy zipped v1 compatible updatersboolean
Produce updaters and their signatures or not
Updater type
V1Compatible
"v1Compatible"
,Generates lagacy zipped v1 compatible updaters
Generates lagacy zipped v1 compatible updaters
Value
Any of the following:
null
Represents a null JSON value.boolean
Represents a [bool
].Number
Represents a valid ACL [Number
].string
Represents a [String
].Value
[] Represents a list of other [Value
]s.- Represents a map of [
String
] keys to [Value
]s. Allows additional properties:Value
All supported ACL values.
WebviewInstallMode
One of the following:
- Do not install the Webview2 as part of the Windows Installer. Object Properties: - type (required) ##### type
"skip"
- Download the bootstrapper and run it. Requires an internet connection. Results in a smaller installer size, but is not recommended on Windows 7. Object Properties: - silent - type (required) ##### silent
boolean
Instructs the installer to run the bootstrapper in silent mode. Defaults totrue
. Default:true
##### type"downloadBootstrapper"
- Embed the bootstrapper and run it. Requires an internet connection. Increases the installer size by around 1.8MB, but offers better support on Windows 7. Object Properties: - silent - type (required) ##### silent
boolean
Instructs the installer to run the bootstrapper in silent mode. Defaults totrue
. Default:true
##### type"embedBootstrapper"
- Embed the offline installer and run it. Does not require an internet connection. Increases the installer size by around 127MB. Object Properties: - silent - type (required) ##### silent
boolean
Instructs the installer to run the installer in silent mode. Defaults totrue
. Default:true
##### type"offlineInstaller"
- Embed a fixed webview2 version and use it at runtime. Increases the installer size by around 180MB. Object Properties: - path (required) - type (required) ##### path
string
The path to the fixed runtime to use. The fixed version can be downloaded on the official website. The.cab
file must be extracted to a folder and this folder path must be defined on this field. ##### type"fixedRuntime"
Install modes for the Webview2 runtime.
Note that for the updater bundle [Self::DownloadBootstrapper
] is used.
For more information see <https://v2.tauri.app/distribute/windows-installer/#webview2-installation-options>.
WebviewUrl
Any of the following:
string
formatted asuri
An external URL. Must use either thehttp
orhttps
schemes.string
The path portion of an app URL. For instance, to loadtauri://localhost/users/john
, you can simply provideusers/john
in this configuration.string
formatted asuri
A custom protocol url, for example,doom://index.html
An URL to open on a Tauri webview window.
WindowConfig
The window configuration object.
See more: <https://v2.tauri.app/reference/config/#windowconfig>
Object Properties:
- acceptFirstMouse
- additionalBrowserArgs
- alwaysOnBottom
- alwaysOnTop
- browserExtensionsEnabled
- center
- closable
- contentProtected
- create
- decorations
- dragDropEnabled
- focus
- fullscreen
- height
- hiddenTitle
- incognito
- label
- maxHeight
- maximizable
- maximized
- maxWidth
- minHeight
- minimizable
- minWidth
- parent
- proxyUrl
- resizable
- shadow
- skipTaskbar
- tabbingIdentifier
- theme
- title
- titleBarStyle
- transparent
- url
- userAgent
- visible
- visibleOnAllWorkspaces
- width
- windowEffects
- x
- y
- zoomHotkeysEnabled
acceptFirstMouse
boolean
Whether clicking an inactive window also clicks through to the webview on macOS.
additionalBrowserArgs
string
| null
Defines additional browser arguments on Windows. By default wry passes --disable-features=msWebOOUI,msPdfOOUI,msSmartScreenProtection
so if you use this method, you also need to disable these components by yourself if you want.
alwaysOnBottom
boolean
Whether the window should always be below other windows.
alwaysOnTop
boolean
Whether the window should always be on top of other windows.
browserExtensionsEnabled
boolean
Whether browser extensions can be installed for the webview process
Platform-specific:
- Windows: Enables the WebView2 environment’s
AreBrowserExtensionsEnabled
- MacOS / Linux / iOS / Android - Unsupported.
center
boolean
Whether or not the window starts centered or not.
closable
boolean
Whether the window’s native close button is enabled or not.
Platform-specific
- Linux: “GTK+ will do its best to convince the window manager not to show a close button. Depending on the system, this function may not have any effect when called on a window that is already visible”
- iOS / Android: Unsupported.
Default: true
contentProtected
boolean
Prevents the window contents from being captured by other apps.
create
boolean
Whether Tauri should create this window at app startup or not.
When this is set to false
you must manually grab the config object via app.config().app.windows
and create it with WebviewWindowBuilder::from_config
.
Default: true
decorations
boolean
Whether the window should have borders and bars.
Default: true
dragDropEnabled
boolean
Whether the drag and drop is enabled or not on the webview. By default it is enabled.
Disabling it is required to use HTML5 drag and drop on the frontend on Windows.
Default: true
focus
boolean
Whether the window will be initially focused or not.
Default: true
fullscreen
boolean
Whether the window starts as fullscreen or not.
height
number
formatted as double
The window height.
Default: 600
hiddenTitle
boolean
If true
, sets the window title to be hidden on macOS.
incognito
boolean
Whether or not the webview should be launched in incognito mode.
Platform-specific:
- Android: Unsupported.
label
string
The window identifier. It must be alphanumeric.
Default: "main"
maxHeight
number
| null
formatted as double
The max window height.
maximizable
boolean
Whether the window’s native maximize button is enabled or not. If resizable is set to false, this setting is ignored.
Platform-specific
- macOS: Disables the “zoom” button in the window titlebar, which is also used to enter fullscreen mode.
- Linux / iOS / Android: Unsupported.
Default: true
maximized
boolean
Whether the window is maximized or not.
maxWidth
number
| null
formatted as double
The max window width.
minHeight
number
| null
formatted as double
The min window height.
minimizable
boolean
Whether the window’s native minimize button is enabled or not.
Platform-specific
- Linux / iOS / Android: Unsupported.
Default: true
minWidth
number
| null
formatted as double
The min window width.
parent
string
| null
Sets the window associated with this label to be the parent of the window to be created.
Platform-specific
- Windows: This sets the passed parent as an owner window to the window to be created.
From MSDN owned windows docs:
- An owned window is always above its owner in the z-order.
- The system automatically destroys an owned window when its owner is destroyed.
- An owned window is hidden when its owner is minimized.
- Linux: This makes the new window transient for parent, see <https://docs.gtk.org/gtk3/method.Window.set_transient_for.html>
- macOS: This adds the window as a child of parent, see <https://developer.apple.com/documentation/appkit/nswindow/1419152-addchildwindow?language=objc>
proxyUrl
string
| null
formatted as uri
The proxy URL for the WebView for all network requests.
Must be either a http://
or a socks5://
URL.
Platform-specific
- macOS: Requires the
macos-proxy
feature flag and only compiles for macOS 14+.
resizable
boolean
Whether the window is resizable or not. When resizable is set to false, native window’s maximize button is automatically disabled.
Default: true
shadow
boolean
Whether or not the window has shadow.
Platform-specific
- Windows:
false
has no effect on decorated window, shadow are always ON.true
will make undecorated window have a 1px white border, and on Windows 11, it will have a rounded corners.
- Linux: Unsupported.
Default: true
skipTaskbar
boolean
If true
, hides the window icon from the taskbar on Windows and Linux.
tabbingIdentifier
string
| null
Defines the window tabbing identifier for macOS.
Windows with matching tabbing identifiers will be grouped together. If the tabbing identifier is not set, automatic tabbing will be disabled.
theme
Theme
| null
The initial window theme. Defaults to the system theme. Only implemented on Windows and macOS 10.14+.
title
string
The window title.
Default: "Tauri App"
titleBarStyle
The style of the macOS title bar.
Default: "Visible"
transparent
boolean
Whether the window is transparent or not.
Note that on macOS
this requires the macos-private-api
feature flag, enabled under tauri > macOSPrivateApi
.
WARNING: Using private APIs on macOS
prevents your application from being accepted to the App Store
.
url
The window webview URL.
Default: "index.html"
userAgent
string
| null
The user agent for the webview
visible
boolean
Whether the window is visible or not.
Default: true
visibleOnAllWorkspaces
boolean
Whether the window should be visible on all workspaces or virtual desktops.
Platform-specific
- Windows / iOS / Android: Unsupported.
width
number
formatted as double
The window width.
Default: 800
windowEffects
WindowEffectsConfig
| null
Window effects.
Requires the window to be transparent.
Platform-specific:
- Windows: If using decorations or shadows, you may want to try this workaround <https://github.com/tauri-apps/tao/issues/72#issuecomment-975607891>
- Linux: Unsupported
x
number
| null
formatted as double
The horizontal position of the window’s top left corner
y
number
| null
formatted as double
The vertical position of the window’s top left corner
zoomHotkeysEnabled
boolean
Whether page zooming by hotkeys is enabled
Platform-specific:
-
Windows: Controls WebView2’s
IsZoomControlEnabled
setting. -
MacOS / Linux: Injects a polyfill that zooms in and out with
ctrl/command
+-/=
, 20% in each step, ranging from 20% to 1000%. Requireswebview:allow-set-webview-zoom
permission -
Android / iOS: Unsupported.
WindowEffect
One of the following:
"appearanceBased"
A default material appropriate for the view’s effectiveAppearance. macOS 10.14-"light"
macOS 10.14-"dark"
macOS 10.14-"mediumLight"
macOS 10.14-"ultraDark"
macOS 10.14-"titlebar"
macOS 10.10+"selection"
macOS 10.10+"menu"
macOS 10.11+"popover"
macOS 10.11+"sidebar"
macOS 10.11+"headerView"
macOS 10.14+"sheet"
macOS 10.14+"windowBackground"
macOS 10.14+"hudWindow"
macOS 10.14+"fullScreenUI"
macOS 10.14+"tooltip"
macOS 10.14+"contentBackground"
macOS 10.14+"underWindowBackground"
macOS 10.14+"underPageBackground"
macOS 10.14+"mica"
Mica effect that matches the system dark perefence Windows 11 Only"micaDark"
Mica effect with dark mode but only if dark mode is enabled on the system Windows 11 Only"micaLight"
Mica effect with light mode Windows 11 Only"tabbed"
Tabbed effect that matches the system dark perefence Windows 11 Only"tabbedDark"
Tabbed effect with dark mode but only if dark mode is enabled on the system Windows 11 Only"tabbedLight"
Tabbed effect with light mode Windows 11 Only"blur"
Windows 7/10/11(22H1) Only ##### Notes This effect has bad performance when resizing/dragging the window on Windows 11 build 22621."acrylic"
Windows 10/11 Only ##### Notes This effect has bad performance when resizing/dragging the window on Windows 10 v1903+ and Windows 11 build 22000.
Platform-specific window effects
WindowEffectsConfig
The window effects configuration object
Object Properties:
- color
- effects (required)
- radius
- state
color
Color
| null
Window effect color. Affects [WindowEffect::Blur
] and [WindowEffect::Acrylic
] only
on Windows 10 v1903+. Doesn’t have any effect on Windows 7 or Windows 11.
effects
List of Window effects to apply to the Window. Conflicting effects will apply the first one and ignore the rest.
radius
number
| null
formatted as double
Window effect corner radius macOS Only
state
WindowEffectState
| null
Window effect state macOS Only
WindowEffectState
One of the following:
"followsWindowActiveState"
Make window effect state follow the window’s active state"active"
Make window effect state always active"inactive"
Make window effect state always inactive
Window effect state macOS only
<https://developer.apple.com/documentation/appkit/nsvisualeffectview/state>
WindowsConfig
Windows bundler configuration.
See more: <https://v2.tauri.app/reference/config/#windowsconfig>
Object Properties:
- allowDowngrades
- certificateThumbprint
- digestAlgorithm
- nsis
- signCommand
- timestampUrl
- tsp
- webviewInstallMode
- wix
allowDowngrades
boolean
Validates a second app installation, blocking the user from installing an older version if set to false
.
For instance, if 1.2.1
is installed, the user won’t be able to install app version 1.2.0
or 1.1.5
.
The default value of this flag is true
.
Default: true
certificateThumbprint
string
| null
Specifies the SHA1 hash of the signing certificate.
digestAlgorithm
string
| null
Specifies the file digest algorithm to use for creating file signatures. Required for code signing. SHA-256 is recommended.
nsis
NsisConfig
| null
Configuration for the installer generated with NSIS.
signCommand
CustomSignCommandConfig
| null
Specify a custom command to sign the binaries.
This command needs to have a %1
in args which is just a placeholder for the binary path,
which we will detect and replace before calling the command.
By Default we use signtool.exe
which can be found only on Windows so
if you are on another platform and want to cross-compile and sign you will
need to use another tool like osslsigncode
.
timestampUrl
string
| null
Server to use during timestamping.
tsp
boolean
Whether to use Time-Stamp Protocol (TSP, a.k.a. RFC 3161) for the timestamp server. Your code signing provider may use a TSP timestamp server, like e.g. SSL.com does. If so, enable TSP by setting to true.
webviewInstallMode
The installation mode for the Webview2 runtime.
wix
WixConfig
| null
Configuration for the MSI generated with WiX.
WixConfig
Configuration for the MSI bundle using WiX.
See more: <https://v2.tauri.app/reference/config/#wixconfig>
Object Properties:
- bannerPath
- componentGroupRefs
- componentRefs
- dialogImagePath
- enableElevatedUpdateTask
- featureGroupRefs
- featureRefs
- fragmentPaths
- language
- mergeRefs
- template
- upgradeCode
bannerPath
string
| null
Path to a bitmap file to use as the installation user interface banner. This bitmap will appear at the top of all but the first page of the installer.
The required dimensions are 493px × 58px.
componentGroupRefs
string
[]
The ComponentGroup element ids you want to reference from the fragments.
Default: []
componentRefs
string
[]
The Component element ids you want to reference from the fragments.
Default: []
dialogImagePath
string
| null
Path to a bitmap file to use on the installation user interface dialogs. It is used on the welcome and completion dialogs. The required dimensions are 493px × 312px.
enableElevatedUpdateTask
boolean
Create an elevated update task within Windows Task Scheduler.
featureGroupRefs
string
[]
The FeatureGroup element ids you want to reference from the fragments.
Default: []
featureRefs
string
[]
The Feature element ids you want to reference from the fragments.
Default: []
fragmentPaths
string
[]
A list of paths to .wxs files with WiX fragments to use.
Default: []
language
The installer languages to build. See <https://docs.microsoft.com/en-us/windows/win32/msi/localizing-the-error-and-actiontext-tables>.
Default: "en-US"
mergeRefs
string
[]
The Merge element ids you want to reference from the fragments.
Default: []
template
string
| null
A custom .wxs template to use.
upgradeCode
string
| null
formatted as uuid
A GUID upgrade code for MSI installer. This code must stay the same across all of your updates, otherwise, Windows will treat your update as a different app and your users will have duplicate versions of your app.
By default, tauri generates this code by generating a Uuid v5 using the string <productName>.exe.app.x64
in the DNS namespace.
You can use Tauri’s CLI to generate and print this code for you, run tauri inspect wix-upgrade-code
.
It is recommended that you set this value in your tauri config file to avoid accidental changes in your upgrade code whenever you want to change your product name.
WixLanguage
Any of the following:
string
A single language to build, without configuration.string
[] A list of languages to build, without configuration.- A map of languages and its configuration. Allows additional properties:
WixLanguageConfig
The languages to build using WiX.
WixLanguageConfig
Configuration for a target language for the WiX build.
See more: <https://v2.tauri.app/reference/config/#wixlanguageconfig>
Object Properties:
- localePath
localePath
string
| null
The path to a locale (.wxl
) file. See <https://wixtoolset.org/documentation/manual/v3/howtos/ui_and_localization/build_a_localized_version.html>.
© 2024 Tauri Contributors. CC-BY / MIT