Rework resource guide (#3485)

Legend-Master · FabianLars · web-flow · commit d459e7ca1c3d · 2025-09-02T19:29:58.000+02:00
Co-authored-by: FabianLars &lt;FabianLars@users.noreply.github.com&gt;
Co-authored-by: FabianLars &lt;github@fabianlars.de&gt;
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -3,5 +3,8 @@
   "prettier.documentSelectors": ["**/*.astro"],
   "[astro]": {
     "editor.defaultFormatter": "astro-build.astro-vscode"
+  },
+  "[mdx]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
   }
 }
diff --git a/src/content/docs/develop/resources.mdx b/src/content/docs/develop/resources.mdx
@@ -3,49 +3,130 @@ title: Embedding Additional Files
 i18nReady: true
 ---
 
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
 You may need to include additional files in your application bundle that aren't part of your frontend (your `frontendDist`) directly or which are too big to be inlined into the binary. We call these files `resources`.
 
-To bundle the files of your choice, you can add the `resources` property to the `bundle` object in your `tauri.conf.json` file.
+## Configuration
 
-See more about `tauri.conf.json` configuration [here][tauri.bundle].
+To bundle the files of your choice, add the `resources` property to the `bundle` object in your `tauri.conf.json` file.
 
-`resources` expects a list of strings targeting files or directories either with absolute or relative paths. It supports glob patterns in case you need to include multiple files from a directory.
+To include a list of files:
 
-Here is a sample to illustrate the configuration. This is not a complete `tauri.conf.json` file:
+<Tabs syncKey="explanation">
+<TabItem label="Syntax">
 
 ```json title=tauri.conf.json
 {
   "bundle": {
     "resources": [
+      "./path/to/some-file.txt",
+      "/absolute/path/to/textfile.txt",
+      "../relative/path/to/jsonfile.json",
+      "some-folder/",
+      "resources/**/*.md"
+    ]
+  }
+}
+```
+
+</TabItem>
+<TabItem label="Explanation">
+
+```json title=tauri.conf.json5
+{
+  "bundle": {
+    "resources": [
+      // Will be placed to `$RESOURCE/path/to/some-file.txt`
+      "./path/to/some-file.txt",
+
+      // The root in an abosolute path will be replaced by `_root_`,
+      // so `textfile.txt` will be placed to `$RESOURCE/_root_/absolute/path/to/textfile.txt`
       "/absolute/path/to/textfile.txt",
-      "relative/path/to/jsonfile.json",
-      "resources/**/*"
+
+      // `..` in a relative path will be replaced by `_up_`,
+      // so `jsonfile.json` will be placed to `$RESOURCE/_up_/relative/path/to/textfile.txt`,
+      "../relative/path/to/jsonfile.json",
+
+      // If the path is a directory, the entire directory will be copied to the `$RESOURCE` directory,
+      // preserving the original structures, for example:
+      //   - `some-folder/file.txt`                   -> `$RESOURCE/some-folder/file.txt`
+      //   - `some-folder/another-folder/config.json` -> `$RESOURCE/some-folder/another-folder/config.json`
+      // This is the same as `some-folder/**/*`
+      "some-folder/",
+
+      // You can also include multiple files at once through glob patterns.
+      // All the `.md` files inside `resources` will be placed to `$RESOURCE/resources/`,
+      // preserving their original directory structures, for example:
+      //   - `resources/index.md`      -> `$RESOURCE/resources/index.md`
+      //   - `resources/docs/setup.md` -> `$RESOURCE/resources/docs/setup.md`
+      "resources/**/*.md"
     ]
   }
 }
 ```
 
-Alternatively the `resources` config also accepts a map object if you want to change where the files will be copied to. Here is a sample that shows how to include files from different sources into the same `resources` folder:
+</TabItem>
+</Tabs>
+
+The bundled files will be in `$RESOURCES/` with the original directory structure preserved,
+for example: `./path/to/some-file.txt` -> `$RESOURCE/path/to/some-file.txt`
+
+To fine control where the files will get copied to, use a map instead:
+
+<Tabs syncKey="explanation">
+<TabItem label="Syntax">
 
 ```json title=tauri.conf.json
 {
   "bundle": {
     "resources": {
       "/absolute/path/to/textfile.txt": "resources/textfile.txt",
       "relative/path/to/jsonfile.json": "resources/jsonfile.json",
-      "resources/**/*": "resources/"
+      "resources/": "",
+      "docs/**/*md": "website-docs/"
     }
   }
 }
 ```
 
-:::note
+</TabItem>
+<TabItem label="Explanation">
+
+```json title=tauri.conf.json5
+{
+  "bundle": {
+    "resources": {
+      // `textfile.txt` will be placed to `$RESOURCE/resources/textfile.txt`
+      "/absolute/path/to/textfile.txt": "resources/textfile.txt",
 
-In Tauri's [permission system](/reference/acl/capability/), absolute paths and paths containing parent components (`../`) can only be allowed via `"$RESOURCE/**"`. Relative paths like `"path/to/file.txt"` can be allowed explicitly via `"$RESOURCE/path/to/file.txt"`.
+      // `jsonfile.json` will be placed to `$RESOURCE/resources/jsonfile.json`
+      "relative/path/to/jsonfile.json": "resources/jsonfile.json",
 
-:::
+      // Copy the entire directory to `$RESOURCE`, preserving the original structures,
+      // the target is "" which means it will be placed directly in the resource directory `$RESOURCE`, for example:
+      //   - `resources/file.txt`                -> `$RESOURCE/file.txt`
+      //   - `resources/some-folder/config.json` -> `$RESOURCE/some-folder/config.json`
+      "resources/": "",
+
+      // When using glob patterns, the behavior is different from the list one,
+      // all the matching files will be placed to the target directory without preserving the original file structures
+      // for example:
+      //   - `docs/index.md`         -> `$RESOURCE/website-docs/index.md`
+      //   - `docs/plugins/setup.md` -> `$RESOURCE/website-docs/setup.md`
+      "docs/**/*md": "website-docs/"
+    }
+  }
+}
+```
 
-## Source path syntax
+</TabItem>
+</Tabs>
+
+To learn about where `$RESOURCE` resolves to on each platforms, see the documentation of [`resource_dir`]
+
+<details>
+<summary>Source path syntax</summary>
 
 In the following explanations "target resource directory" is either the value after the colon in the object notation, or a reconstruction of the original file paths in the array notation.
 
@@ -56,19 +137,111 @@ In the following explanations "target resource directory" is either the value af
 - `"dir/**/*"`: copies all files in the `dir` directory _recursively_ (all files in `dir/` and all files in all sub-directories) into the target resource directory.
 - `"dir/**/**`: throws an error because `**` only matches directories and therefore no files can be found.
 
-## Accessing files in Rust
+</details>
+
+## Resolve resource file paths
+
+To resolve the path for a resource file, instead of manually calculating the path, use the following APIs
 
-In this example we want to bundle additional i18n json files that look like this:
+<Tabs syncKey="lang">
+<TabItem label="Rust">
 
-```json title=de.json
+On the Rust side, you need an instance of the [`PathResolver`] which you can get from [`App`] and [`AppHandle`],
+then call [`PathResolver::resolve`]:
+
+```rust
+tauri::Builder::default()
+  .setup(|app| {
+    let resource_path = app.path().resolve("lang/de.json", BaseDirectory::Resource)?;
+    Ok(())
+  })
+```
+
+To use it in a command:
+
+```rust
+#[tauri::command]
+fn hello(handle: tauri::AppHandle) {
+  let resource_path = handle.path().resolve("lang/de.json", BaseDirectory::Resource)?;
+}
+```
+
+</TabItem>
+<TabItem label="JavaScript">
+
+To resolve the path in JavaScript, use [`resolveResource`]:
+
+```javascript
+import { resolveResource } from '@tauri-apps/api/path';
+const resourcePath = await resolveResource('lang/de.json');
+```
+
+</TabItem>
+</Tabs>
+
+### Path syntax
+
+The path in the API calls can be either a normal relative path like `folder/json_file.json` that resolves to `$RESOURCE/folder/json_file.json`,
+or a paths like `../relative/folder/toml_file.toml` that resolves to `$RESOURCE/_up_/relative/folder/toml_file.toml`,
+these APIs use the same rules as you write `tauri.conf.json > bundle > resources`, for example:
+
+```json title=tauri.conf.json
+{
+  "bundle": {
+    "resources": ["folder/json_file.json", "../relative/folder/toml_file.toml"]
+  }
+}
+```
+
+```rust
+let json_path = app.path().resolve("folder/json_file.json", BaseDirectory::Resource)?;
+let toml_path = app.path().resolve("../relative/folder/toml_file.toml", BaseDirectory::Resource)?;
+```
+
+### Android
+
+Currently the resources are stored in the APK as assets so the return value of those APIs are not normal file system paths,
+we use a special URI prefix `asset://localhost/` here that can be used with the [`fs` plugin],
+with that, you can read the files through [`FsExt::fs`] like this:
+
+```rust
+let resource_path = app.path().resolve("lang/de.json", BaseDirectory::Resource).unwrap();
+let json = app.fs().read_to_string(&resource_path);
+```
+
+If you want or must have the resource files to be on a real file system, copy the contents out manually through the [`fs` plugin]
+
+## Reading resource files
+
+In this example we want to bundle additional i18n json files like this:
+
+```
+.
+├── src-tauri/
+│   ├── tauri.conf.json
+│   ├── lang/
+│   │   ├── de.json
+│   │   └── en.json
+│   └── ...
+└── ...
+```
+
+```json title=tauri.conf.json
+{
+  "bundle": {
+    "resources": ["lang/*"]
+  }
+}
+```
+
+```json title=lang/de.json
 {
   "hello": "Guten Tag!",
   "bye": "Auf Wiedersehen!"
 }
 ```
 
-In this case, we store these files in a `lang` directory next to the `tauri.conf.json`.
-For this we add `"lang/*"` to `resources` as shown above.
+### Rust
 
 On the Rust side, you need an instance of the [`PathResolver`] which you can get from [`App`] and [`AppHandle`]:
 
@@ -79,8 +252,11 @@ tauri::Builder::default()
     // `tauri.conf.json > bundle > resources`
     let resource_path = app.path().resolve("lang/de.json", BaseDirectory::Resource)?;
 
-    let file = std::fs::File::open(&resource_path).unwrap();
-    let lang_de: serde_json::Value = serde_json::from_reader(file).unwrap();
+    let json = std::fs::read_to_string(&resource_path).unwrap();
+    // Or when dealing with Android, use the file system plugin instead
+    // let json = app.fs().read_to_string(&resource_path);
+
+    let lang_de: serde_json::Value = serde_json::from_str(json).unwrap();
 
     // This will print 'Guten Tag!' to the terminal
     println!("{}", lang_de.get("hello").unwrap());
@@ -94,18 +270,21 @@ tauri::Builder::default()
 fn hello(handle: tauri::AppHandle) -> String {
     let resource_path = handle.path().resolve("lang/de.json", BaseDirectory::Resource)?;
 
-    let file = std::fs::File::open(&resource_path).unwrap();
-    let lang_de: serde_json::Value = serde_json::from_reader(file).unwrap();
+    let json = std::fs::read_to_string(&resource_path).unwrap();
+    // Or when dealing with Android, use the file system plugin instead
+    // let json = handle.fs().read_to_string(&resource_path);
+
+    let lang_de: serde_json::Value = serde_json::from_str(json).unwrap();
 
     lang_de.get("hello").unwrap()
 }
 ```
 
-## Accessing files in JavaScript
+### JavaScript
 
-For the JavaScript side, you can either use a command like the one above and call it through `await invoke('hello')` or access the files using the [`plugin-fs`]
+For the JavaScript side, you can either use a command like the one above and call it through `await invoke('hello')` or access the files using the [`fs` plugin].
 
-When using the [`plugin-fs`], addition from the [basic setup], you'll also need to configure the access control list to enable any [`plugin-fs`] APIs you will need as well as permissions to access the `$RESOURCE` folder:
+When using the [`fs` plugin], in addition to the [basic setup], you'll also need to configure the access control list to enable any plugin APIs you need as well as the permissions to access the `$RESOURCE` folder:
 
 ```json title=src-tauri/capabilities/default.json ins={8-9}
 {
@@ -135,11 +314,78 @@ const langDe = JSON.parse(await readTextFile(resourcePath));
 console.log(langDe.hello); // This will print 'Guten Tag!' to the devtools console
 ```
 
-[tauri.bundle]: /reference/config/#bundleconfig
+## Permissions
+
+Since we replace `../` to `_up_` in relative paths and the root to `_root_` in abosolute paths when using a list,
+those files will be in sub folders inside the resource directory,
+to allow those paths in Tauri's [permission system](/security/capabilities/),
+use `$RESOURCE/**/*` to allow recursive access to those files
+
+### Examples
+
+With a file bundled like this:
+
+```json title=tauri.conf.json
+{
+  "bundle": {
+    "resources": ["../relative/path/to/jsonfile.json"]
+  }
+}
+```
+
+To use it with the [`fs` plugin]:
+
+```json title=src-tauri/capabilities/default.json ins={8-15}
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "main-capability",
+  "description": "Capability for the main window",
+  "windows": ["main"],
+  "permissions": [
+    "core:default",
+    "fs:allow-stat",
+    "fs:allow-read-text-file",
+    "fs:allow-resource-read-recursive",
+    {
+      "identifier": "fs:scope",
+      "allow": ["$RESOURCE/**/*"],
+      "deny": ["$RESOURCE/secret.txt"]
+    }
+  ]
+}
+```
+
+To use it with the [`opener` plugin]:
+
+```json title=src-tauri/capabilities/default.json ins={8-15}
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "main-capability",
+  "description": "Capability for the main window",
+  "windows": ["main"],
+  "permissions": [
+    "core:default",
+    {
+      "identifier": "opener:allow-open-path",
+      "allow": [
+        {
+          "path": "$RESOURCE/**/*"
+        }
+      ]
+    }
+  ]
+}
+```
+
+[`resource_dir`]: https://docs.rs/tauri/latest/tauri/path/struct.PathResolver.html#method.resource_dir
 [`pathresolver`]: https://docs.rs/tauri/latest/tauri/path/struct.PathResolver.html
+[`PathResolver::resolve`]: https://docs.rs/tauri/latest/tauri/path/struct.PathResolver.html#method.resolve
+[`resolveResource`]: https://tauri.app/reference/javascript/api/namespacepath/#resolveresource
 [`app`]: https://docs.rs/tauri/latest/tauri/struct.App.html
 [`apphandle`]: https://docs.rs/tauri/latest/tauri/struct.AppHandle.html
-[`plugin-fs`]: /plugin/file-system/
+[`fs` plugin]: /plugin/file-system/
+[`FsExt::fs`]: https://docs.rs/tauri-plugin-fs/latest/tauri_plugin_fs/trait.FsExt.html#tymethod.fs
 [basic setup]: /plugin/file-system/#setup
 [Scope Permissions]: /plugin/file-system/#scopes
 [scopes]: /plugin/file-system/#scopes
+[`opener` plugin]: /plugin/opener/

Original file line number	Diff line number	Diff line change
`@@ -3,5 +3,8 @@`
`3`	`3`	`"prettier.documentSelectors": ["*/.astro"],`
`4`	`4`	`"[astro]": {`
`5`	`5`	`"editor.defaultFormatter": "astro-build.astro-vscode"`
	`6`	`+ },`
	`7`	`+ "[mdx]": {`
	`8`	`+ "editor.defaultFormatter": "esbenp.prettier-vscode"`
`6`	`9`	`}`
`7`	`10`	`}`