asset protocol

12 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Asset protocol enables serving files from disk to WebView

Tauri can serve files from disk into the WebView through the asset custom protocol. Whether a path is allowed is controlled by app.security.assetProtocol in tauri.conf.json. You must set enable to true and define a scope that lists which filesystem paths may be exposed. Paths resolved at runtime must match that scope, or the WebView will refuse the load.

assetProtocol scope uses FsScope type

assetProtocol.scope uses the same FsScope type as filesystem-related configuration elsewhere. It can be either a JSON array of allowed glob patterns, or a JSON object with allow, optional deny, and optional requireLiteralLeadingDot fields.

Asset protocol patterns support base directory variables

Patterns may start with a base directory variable such as $HOME, $CACHE, $APPCACHE, $APPDATA, or $RESOURCE. See the path / base directory APIs for the full set of variables.

Resolved asset paths are usually absolute

Paths resolved when loading assets are usually absolute (on Linux, often under /home/...). A pattern like ["*/**"] typically does not match those paths because it does not line up with a leading / or a base-directory variable. Prefer patterns such as $HOME/**/* or /home/username/**/* that mirror the resolved path.

Asset protocol array form configuration

The array form allows defining a fixed list of allowed glob patterns. Example: {"app": {"security": {"assetProtocol": {"enable": true, "scope": ["$APPCACHE/**/*", "$RESOURCE/**/*"]}}}}. With the array form you cannot set requireLiteralLeadingDot; use the object form for that.

Asset protocol object form with allow and deny

The object form allows defining allow patterns and optional deny patterns. Example: {"app": {"security": {"assetProtocol": {"enable": true, "scope": {"allow": ["$APPCACHE/**/*"], "deny": ["$APPCACHE/**/secrets/**"]}}}}}. The deny patterns take precedence over allow patterns when both match.

requireLiteralLeadingDot defaults to true on Unix

On Unix, requireLiteralLeadingDot defaults to true. Then wildcard tokens such as *, ?, **, and [...] do not match a path component that starts with . (dotfiles and dot-directories such as .cache or .ssh). A pattern like $HOME/** can allow /home/user/Documents/file.png but not /home/user/.cache/myapp/preview.png because .cache is dot-prefixed.

requireLiteralLeadingDot false allows matching dot-prefixed paths

To allow dot-prefixed components under a broad glob, set requireLiteralLeadingDot to false on the object scope. This widens what the WebView can load. Example: {"app": {"security": {"assetProtocol": {"enable": true, "scope": {"requireLiteralLeadingDot": false, "allow": ["$HOME/**/*"]}}}}}. Review security implications carefully.

Prefer **/* over bare ** for file matching in asset protocol

For globs that should match files under a tree, prefer **/* (and variants like $DIR/**/*) rather than bare **, consistent with other Tauri path examples. Bare ** is easy to misuse when you intend "everything under this directory recursively."

Highly permissive asset protocol configuration

A highly permissive configuration that matches all files including dot-prefixed segments: {"app": {"security": {"assetProtocol": {"enable": true, "scope": {"requireLiteralLeadingDot": false, "allow": ["**/*"]}}}}}. This is not a default recommendation; it increases exposure of hidden and sensitive files.

Use persisted-scope plugin for dynamic asset protocol paths

Static entries in tauri.conf.json describe static allow/deny patterns and do not replace runtime workflows where the user picks arbitrary folders or files. Those paths may need to be persisted across restarts using the persisted-scope plugin. To persist asset/protocol-related scope with that plugin, enable its protocol-asset Cargo feature in src-tauri/Cargo.toml: tauri-plugin-persisted-scope = { version = "2", features = ["protocol-asset"] }.

Asset protocol error messages and troubleshooting

Common error: "asset protocol not configured to allow the path" means the path must match an allow pattern, with deny overriding allow. Use absolute patterns or $VAR/$HOME style variables that match how the path is resolved on disk. On Unix, dotfiles not matching is likely due to requireLiteralLeadingDot defaulting to true. Broad ** patterns should typically be **/* instead. Patterns like ["*/**"] never match on Linux because resolved paths are absolute.

Give your agent this brain