tauri-apps/tauri
1
1
Fork 0
mirror of https://github.com/tauri-apps/tauri.git synced 2024-12-24 11:14:40 +03:00
Code Issues Packages Projects Releases Wiki Activity
160fb0529f
tauri/docs/api/config.md
Lucas Fernandes Nogueira 160fb0529f
feat(core): improve RPC security, closes #814 (#2047)
2021-06-22 17:29:10 -03:00

370 lines
27 KiB
Markdown
Raw Blame History

---
title: Configuration
---
import Properties from '@theme/Properties'
import Array from '@theme/Array'
import Alert from '@theme/Alert'
The `tauri.conf.json` is a file generated by the `tauri init` command (see <a href="/docs/api/cli#tauri-init">here</a>) that lives in your Tauri application source directory (src-tauri).
Once generated, you may modify it at will to customize your Tauri application.
It's composed of the following properties:
## `build`
<Properties anchorRoot="build" rows={[
{property: "distDir", type: "string", description: `The path—either absolute or relative—to the production-ready webpage/webapp directory that will be bundled by Tauri.
<div class="alert alert--info" role="alert" style="margin-top: 10px;">
The target directory <em>must</em> contain an index.html file.
</div>`},
{property: "devPath", type: "string", description: `Can be a path—either absolute or relative—to a folder or a URL (like a live reload server).`},
{property: "beforeDevCommand", optional: true, type: "string", description: `A command to run before starting Tauri in dev mode.`},
{property: "beforeBuildCommand", optional: true, type: "string", description: `A command to run before starting Tauri in build mode.`},
{property: "withGlobalTauri", optional: true, type: "boolean", description: "Enables the API injection to the window.__TAURI__ object. Useful if you're using Vanilla JS instead of importing the API using Rollup or Webpack. Reduces the command security since any external code can access it, so be careful with XSS attacks."}
]}/>
```js title=Example
"build": {
"distDir": "../dist",
"devPath": "http://localhost:4000",
"beforeDevCommand": "npm run dev",
"beforeBuildCommand": "npm run build",
"withGlobalTauri": false
}
```
## `package`
<Properties anchorRoot="package" rows={[
{ property: "name", optional: true, type: "string", description: `Application binary name. Converted to snake-case on Linux.` },
{ property: "version", optional: true, type: "string", description: `Application version.` }
]}/>
## `tauri`
<Properties anchorRoot="tauri" rows={[
{
property: "cli", optional: true, type: "CliConfig",
child: <Properties anchorRoot="tauri.cli" rows={[
{ property: "args", optional: true, type: "CliArg[]", description: `List of args for the command.`, child: <Array type="CliArg" name="arg"><Properties anchorRoot="tauri.cli.args" rows={[
{ property: "short", optional: true, type: "string", description: `the short version of the argument, without the preceding hyphen (the "-" character).
<div class="alert alert--info" role="alert" style="margin-top: 10px;">
Any leading hyphen will be stripped, and only the first non hyphen character will be used as the short version.
</div>` },
{ property: "name", type: "string", description: `The unique argument name.` },
{ property: "description", optional: true, type: "string", description: `The argument description which will be shown on the help information. Typically, this is a short (one line) description of the arg.` },
{ property: "longDescription", optional: true, type: "string", description: `The argument long description which will be shown on the help information.
Typically, this a more detailed (multi-line) message that describes the argument` },
{ property: "takesValue", optional: true, type: "boolean", description: `Specifies that the argument takes a value at runtime.
<div class="alert alert--info" role="alert" style="margin-top: 10px;">
Values for arguments may be specified in any of the following methods:
<ul>
<li>Using a space such as <code>-o value</code> or <code>--option value</code></li>
<li>Using an equals and no space such as <code>-o=value</code> or <code>--option=value</code></li>
<li>Use a short and no space such as <code>-ovalue</code></li>
</ul>
</div>`
},
{ property: "index", type: "number", optional: true, description: `The positional argument index, starting at 1.
<div class="alert alert--info" role="alert" style="margin-top: 10px;">
The index refers to position according to other positional argument. It does not define position in the argument list as a whole.
When utilized with multiple=true, only the last positional argument may be defined as multiple (i.e. the one with the highest index).
</div>`
},
{ property: "multiple", optional: true, type: "boolean", description: `Specifies that the argument may appear more than once.
For flags, this results in the number of occurrences of the flag being recorded. For example <code>-ddd</code> or <code>-d -d -d</code> would count as three occurrences.
For options, there is a distinct difference in multiple occurrences vs multiple values. For example, <code>--opt val1 val2</code> is one occurrence, but two values. Whereas <code>--opt val1 --opt val2</code> is two occurrences.` },
{ property: "possibleValues", optional: true, type: "string[]", description: `Specifies a list of possible values for this argument. At runtime, the CLI verifies that only one of the specified values was used, or fails with an error message.` },
{ property: "minValues", optional: true, type: "number", description: `Specifies the minimum number of values for this argument.
For example, if you had a -f &lt;file&gt; argument where you wanted at least 2 "files" you would set <code>minValues: 2</code>, and this argument would be satisfied if the user provided, 2 or more values.` },
{ property: "maxValues", optional: true, type: "number", description: `Specifies the maximum number of values for this argument.
For example, if you had a -f &lt;file&gt; argument where you wanted up to 3 "files" you would set <code>max_values: 3</code>, and this argument would be satisfied if the user provided, 1, 2, or 3 values.` },
{ property: "required", optional: true, type: "boolean", description: `Sets whether or not the argument is required by default.
"required by default" means it is required, when no other conflicting rules have been evaluated
conflicting rules take precedence over being required.` },
{ property: "requiredUnless", optional: true, type: "string", description: `Sets an arg that overrides this arg's required setting.<br/>
i.e. this arg will be required unless this other argument is present.` },
{ property: "requiredUnlessAll", optional: true, type: "string[]", description: `Sets args that override this arg's required setting.<br/>
i.e. this arg will be required unless all these other arguments are present.` },
{ property: "requiredUnlessOne", optional: true, type: "string[]", description: `Sets args that override this arg's required setting.<br/>
i.e. this arg will be required unless at least one of these other arguments are present.` },
{ property: "conflictsWith", optional: true, type: "string", description: `Sets a conflicting argument by name
i.e. when using this argument, the following argument can't be present and vice versa.` },
{ property: "conflictsWithAll", optional: true, type: "string", description: `The same as <code>"conflictsWith"</code> but allows specifying multiple two-way conflicts per argument.` },
{ property: "requires", optional: true, type: "string", description: `Sets an argument by name that is required when this one is present.<br/>
i.e. when using this argument, the following argument must be present.` },
{ property: "requiresAll", optional: true, type: "string[]", description: `Sets multiple arguments by names that are required when this one is present.<br/>
i.e. when using this argument, the following arguments must be present.` },
{ property: "requiresIf", optional: true, type: "[string, string]", description: `Allows a conditional requirement with the signature <code>[arg: string, value: string]</code>.
<div class="alert alert--info" role="alert" style="margin-top: 10px;">
The requirement will only become valid if <code>"arg"</code>'s value equals <code>\${value}</code>.
</div>
` },
{ property: "requiredIf", optional: true, type: "[string, string]", description: `Allows specifying that an argument is required conditionally with the signature <code>[arg: string, value: string]</code>.
<div class="alert alert--info" role="alert" style="margin-top: 10px;">
The requirement will only become valid if the <code>"arg"</code>'s value equals <code>\${value}</code>.
</div>
` },
{ property: "requireEquals", optional: true, type: "boolean", description: `Requires that options use the <code>--option=val</code> syntax.<br/>
i.e. an equals between the option and associated value.` },
]} /></Array> },
{ property: "description", optional: true, type: "string", description: `Command description which will be shown on the help information.` },
{ property: "longDescription", optional: true, type: "string", description: `Command long description which will be shown on the help information.` },
{ property: "beforeHelp", optional: true, type: "string", description: `Adds additional help information to be displayed in addition to auto-generated help.<br/>
This information is displayed before the auto-generated help information.<br/>
This is often used for header information.` },
{ property: "afterHelp", optional: true, type: "string", description: `Adds additional help information to be displayed in addition to auto-generated help.<br/>
This information is displayed after the auto-generated help information.<br/>
This is often used to describe how to use the arguments, or caveats to be noted.` },
{ property: "subcommands", optional: true, type: "{ [name: string]: CliConfig }", description: `List of subcommands of this command.<br/>
Subcommands are effectively sub-apps, because they can contain their own arguments, subcommands, usage, etc.<br/>
They also function just like the app command, in that they get their own auto generated help and usage.` },
]} />
},
{
property: "bundle", type: "object",
child: <Properties anchorRoot="tauri.bundle" rows={[
{ property: "active", optional: true, type: "boolean", description: `Whether we should build your app with tauri-bundler or plain <code>cargo build</code>.` },
{ property: "targets", optional: true, type: "string | string[]", description: `An array of the bundles you want to generate; e.g. ["deb", "app", "msi", "appimage", "dmg"] or the string 'all' to make every supported bundle. By default we bundle everything your target supports (app/dmg on mac, deb/appimage on linux, msi on windows).` },
{ property: "identifier", type: "string", description: `A string that uniquely identifies your application, in reverse-DNS form (for example, "com.example.appname" or "io.github.username.project"). For OS X and iOS, this is used as the bundle's CFBundleIdentifier value; for Windows, this is hashed to create an application GUID.` },
{ property: "icon", optional: true, type: "string[]", description: `A list of (relative to src-tauri) icon paths to use for your application bundle.` },
{ property: "resources", optional: true, type: "string[]", description: `A list of files or directories which will be copied to the resources section of the bundle. Globs are supported.` },
{ property: "externalBin", optional: true, type: "string[]", description: `A list of—either absolute or relative—paths to binaries to embed with your application.
<div class="alert alert--info" role="alert" style="margin-top: 10px;">
Note that Tauri will look for system-specific binaries following the pattern "binary-name{-target-triple}{.system-extension}". <br/>
E.g. you typed "my-binary":
<ul>
<li>"my-binary-x86_64-pc-windows-msvc.exe" for Windows</li>
<li>"my-binary-x86_64-apple-darwin" for macOS</li>
<li>"my-binary-x86_64-unknown-linux-gnu" for Linux</li>
</ul>
so don't forget to provide binaries for <strong>all targeted platforms</strong>.
</div>` },
{ property: "copyright", optional: true, type: "string", description: `A copyright string associated with your application.` },
{ property: "category", optional: true, type: "string", description: `What kind of application this is.
Should be one among the following list: <br/>
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.
` },
{ property: "shortDescription", optional: true, type: "string", description: `A short description of your application.` },
{ property: "longDescription", optional: true, type: "string", description: `A longer, multi-line description of the application.` },
{ property: "deb", optional: true, type: "object", child: <Properties anchorRoot="tauri.bundle.deb" rows={[
{ property: "depends", optional: true, type: "string[]", description: `The list of deb dependencies your application relies on.` },
{ property: "useBootstrapper", optional: true, type: "boolean", description: `Enable the <a href="/en/docs/usage/guides/bundler/debian#bootstrapper">boostrapper script</a>.` },
{ property: "files", optional: true, type: "{ [path: string]: string }", description: `The files to include on the package. See <a href="/en/docs/usage/guides/bundler/debian#custom-files">the debian guide</a>.` }]} />
},
{ property: "windows", optional: true, type: "object", child: <Properties anchorRoot="tauri.bundle.windows" rows={[
{ property: "digestAlgorithm", optional: true, type: "string", description: `Specifies the file digest algorithm to use for creating file signatures. Required for code signing. SHA-256 is recommended.` },
{ property: "certificateThumbprint", optional: true, type: "string[]", description: `Specifies the SHA1 hash of the signing certificate.` },
{ property: "timestampUrl", optional: true, type: "string[]", description: `Server to use during timestamping.` },
{ property: "wix", optional: true, type: "object", child: <Properties anchorRoot="tauri.bundle.windows.wix" rows={[
{ property: "language", optional: true, type: "string", description: `The installer language. See https://docs.microsoft.com/en-us/windows/win32/msi/localizing-the-error-and-actiontext-tables.` },
{ property: "template", optional: true, type: "string", description: `A custom .wxs template to use.` },
{ property: "fragmentPaths", optional: true, type: "string[]", description: `A list of paths to .wxs files with WiX fragments to use.` },
{ property: "componentGroupRefs", optional: true, type: "string[]", description: `The ComponentGroup element ids you want to reference from the fragments.` },
{ property: "componentRefs", optional: true, type: "string[]", description: `The Component element ids you want to reference from the fragments.` },
{ property: "featureGroupRefs", optional: true, type: "string[]", description: `The FeatureGroup element ids you want to reference from the fragments.` },
{ property: "featureRefs", optional: true, type: "string[]", description: `The Feature element ids you want to reference from the fragments.` },
{ property: "mergeRefs", optional: true, type: "string[]", description: `The Merge element ids you want to reference from the fragments.` },
{ property: "skipWebviewInstall", optional: true, type: "boolean", description: `Disables the Webview2 runtime installation after app install.` },
{ property: "license", optional: true, type: "string", description: `The path to the license file to render on the installer. Must be an RTF file, so if a different extension is provided, we convert it to the RTF format.` }]} />
}
]} />
},
{ property: "macOS", optional: true, type: "object", child: <Properties anchorRoot="tauri.bundle.macOS" rows={[
{ property: "frameworks", optional: true, type: "string[]", description: `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.` },
{ property: "minimumSystemVersion", optional: true, type: "string", description: `A version string indicating the minimum macOS X version that the bundled application supports.` },
{ property: "license", optional: true, type: "string", description: `The path to the license file to add to the DMG.` },
{ property: "useBootstrapper", optional: true, type: "boolean", description: `Enable the <a href="#bootstrapper">boostrapper script</a>.` },
{ property: "exceptionDomain", optional: true, type: "string", description: `Allows your application to communicate with the outside world.
<div class="alert alert--info" role="alert" style="margin-top: 10px;">
It should be a lowercase, without port and protocol domain name.
</div>
` },
{ property: "signingIdentity", optional: true, type: "string", description: `Identity to use for code signing.` },
{ property: "entitlements", optional: true, type: "string", description: `Path to the entitlements file.` },
]} /> },
]} />
},
{
property: "allowlist", type: "object",
child: <Properties anchorRoot="tauri.allowlist" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all API features.` },
{
property: "fs", optional: true, type: "object", child: <Properties anchorRoot="tauri.allowlist.fs" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all file system API features.` },
{ property: "readTextFile", optional: true, type: "boolean", description: `Read text file from local filesystem.` },
{ property: "readBinaryFile", optional: true, type: "boolean", description: `Read binary file from local filesystem.` },
{ property: "writeFile", optional: true, type: "boolean", description: `Write text file to local filesystem.` },
{ property: "writeBinaryFile", optional: true, type: "boolean", description: `Write binary file to local filesystem.` },
{ property: "readDir", optional: true, type: "boolean", description: `Read directory from local filesystem.` },
{ property: "copyFile", optional: true, type: "boolean", description: `Copy file from local filesystem.` },
{ property: "createDir", optional: true, type: "boolean", description: `Create directory from local filesystem.` },
{ property: "removeDir", optional: true, type: "boolean", description: `Remove directory from local filesystem.` },
{ property: "removeFile", optional: true, type: "boolean", description: `Remove file from local filesystem.` },
{ property: "renameFile", optional: true, type: "boolean", description: `Rename file from local filesystem.` },
{ property: "path", optional: true, type: "boolean", description: `Resolve system paths.` },
]}/>
},
{
property: "window", optional: true, type: "object", child: <Properties anchorRoot="tauri.allowlist.window" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all window API features.` },
{ property: "create", optional: true, type: "boolean", description: `Allows dynamic window creation.` },
]}/>
},
{
property: "shell", optional: true, type: "object", child: <Properties anchorRoot="tauri.allowlist.shell" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all shell API features.` },
{ property: "execute", optional: true, type: "boolean", description: `Enable binary execution.` },
{ property: "open", optional: true, type: "boolean", description: `Open URL with the user's default application.` },
]}/>
},
{
property: "dialog", optional: true, type: "object", child: <Properties anchorRoot="tauri.allowlist.dialog" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all dialog API features.` },
{ property: "open", optional: true, type: "boolean", description: `Open dialog window to pick files.` },
{ property: "save", optional: true, type: "boolean", description: `Open dialog window to pick where to save files.` },
]}/>
},
{
property: "http", optional: true, type: "object", child: <Properties anchorRoot="tauri.allowlist.http" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all HTTP API features.` },
{ property: "request", optional: true, type: "boolean", description: `Allows making HTTP requests.` },
]}/>
},
{
property: "notification", optional: true, type: "object", child: <Properties anchorRoot="tauri.allowlist.notification" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all notification API features.` },
]}/>
},
{
property: "globalShortcut", optional: true, type: "object", child: <Properties anchorRoot="tauri.allowlist.globalShortcut" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all global shortcut API features.` },
]}/>
},
]} />
},
{
property: "windows", type: "WindowConfig[]",
child: <Array type="WindowConfig" name="window">
<Properties anchorRoot="tauri.windows" rows={[
{ property: "label", type: "string", description: `Window id to reference on the codebase.` },
{ property: "url", type: "string", description: `URL to load on the webview.` },
{ property: "fileDropEnabled", type: "boolean", description: `Whether the file drop handler is enabled or not on the webview. Disabling it is required to use drag and drop on the frontend on Windows.` },
{ property: "center", type: "boolean", description: `Show window in the center of the screen.` },
{ property: "x", type: "number", description: `The horizontal position of the window's top left corner.` },
{ property: "y", type: "number", description: `The vertical position of the window's top left corner.` },
{ property: "width", optional: true, type: "number", description: `Initial window width.` },
{ property: "height", optional: true, type: "number", description: `Initial window height.` },
{ property: "minWidth", type: "number", description: `The minimum window width.` },
{ property: "minHeight", type: "number", description: `The minimum window height.` },
{ property: "maxWidth", type: "number", description: `The maximum window width.` },
{ property: "maxHeight", type: "number", description: `The maximum window height.` },
{ property: "resizable", optional: true, type: "boolean", description: `Whether the window is resizable or not..` },
{ property: "title", type: "string", description: `Window title.` },
{ property: "fullscreen", optional: true, type: "boolean", description: `Whether the window starts as fullscreen or not.` },
{ property: "focus", optional: true, type: "boolean", description: `Whether the window will be initially hidden or focused.` },
{ property: "transparent", optional: true, type: "boolean", description: `Whether the window is transparent or not.` },
{ property: "maximized", optional: true, type: "boolean", description: `Whether the window is maximized or not.` },
{ property: "visible", optional: true, type: "boolean", description: `Whether the window is visible or not.` },
{ property: "decorations", optional: true, type: "boolean", description: `Whether the window should have borders and bars.` },
{ property: "alwaysOnTop", optional: true, type: "boolean", description: `Whether the window should always be on top of other windows.` },
{ property: "skipTaskbar", optional: true, type: "boolean", description: `Whether or not the window icon should be added to the taskbar.` },
]}/>
</Array>
},
{
property: "security", type: "object",
child: <Properties anchorRoot="tauri.security" rows={[
{ property: "csp", optional: true, type: "string", description: `The Content Security Policy.
<div class="alert alert--warning" role="alert" style="margin-top: 10px;">
This is a really important part of the configuration since it helps you ensure your WebView is secured. See more <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP" target="_blank">on Mozilla</a>.
</div>` },
]} />
},
]} />
<!-- Dirty trick to have an anchor without make it appear in the table of contents -->
<div id="bootstrapper"></div>
<Alert title="bootstrapper script">
Instead of launching the app directly, we configure the bundled app to run a script that tries to expose the environment variables to the app; without that you'll have trouble using system CLI apps like Node.js.
</Alert>
```js title=Example
"tauri": {
"cli": {
"description": "Tauri communication example",
"longDescription": null,
"beforeHelp": null,
"afterHelp": null,
"args": [{
"short": "c",
"name": "config",
"takesValue": true,
"description": "Config path"
}, {
"short": "t",
"name": "theme",
"takesValue": true,
"description": "App theme",
"possibleValues": ["light", "dark", "system"]
}, {
"short": "v",
"name": "verbose",
"multipleOccurrences": true,
"description": "Verbosity level"
}],
"subcommands": {
"update": {
"description": "Updates the app",
"longDescription": null,
"beforeHelp": null,
"afterHelp": null,
"args": [{
"short": "b",
"name": "background",
"description": "Update in background"
}],
"subcommands": null
}
}
},
"bundle": {
"active": true,
"targets": ["deb"],
"identifier": "com.tauri.dev",
"icon": ["icons/32x32.png", "icons/128x128.png", "icons/128x128@2x.png", "icons/icon.icns", "icons/icon.ico"],
"resources": [],
"externalBin": [],
"copyright": "",
"category": "DeveloperTool",
"shortDescription": "",
"longDescription": "",
"deb": {
"depends": []
},
"macOS": {
"frameworks": [],
"minimumSystemVersion": "",
"exceptionDomain": ""
}
},
"allowlist": {
"all": true
},
"windows": [{
"title": "Tauri App",
"width": 800,
"height": 600,
"resizable": true,
"fullscreen": false
}],
"security": {
"csp": "default-src blob: data: filesystem: ws: wss: http: https: tauri: 'unsafe-eval' 'unsafe-inline' 'self'"
}
}
```
Reference in New Issue View Git Blame Copy Permalink