File System
Access the file system.
Supported Platforms
This plugin requires a Rust version of at least 1.77.2
Platform | Level | Notes |
---|---|---|
windows | ||
linux | No write access to | |
macos | No write access to | |
android | | Access is restricted to Application folder by default |
ios | | Access is restricted to Application folder by default |
Setup
Install the fs plugin to get started.
Use your project’s package manager to add the dependency:
-
Run the following command in the
src-tauri
folder to add the plugin to the project’s dependencies inCargo.toml
: -
Modify
lib.rs
to initialize the plugin: -
Install the JavaScript Guest bindings using your preferred JavaScript package manager:
Configuration
Android
When using the audio, cache, documents, downloads, picture, public or video directories your app must have access to the external storage.
Include the following permissions to the manifest
tag in the gen/android/app/src/main/AndroidManifest.xml
file:
iOS
Apple requires app developers to specify approved reasons for API usage to enhance user privacy.
You must create a PrivacyInfo.xcprivacy
file in the src-tauri/gen/apple
folder
with the required NSPrivacyAccessedAPICategoryFileTimestamp key and the C617.1 recommended reason.
Usage
The fs plugin is available in both JavaScript and Rust.
Security
This module prevents path traversal, not allowing parent directory accessors to be used (i.e. “/usr/path/to/../file” or ”../path/to/file” paths are not allowed). Paths accessed with this API must be either relative to one of the base directories or created with the path API.
See @tauri-apps/plugin-fs - Security for more information.
Paths
The file system plugin offers two ways of manipulating paths: the base directory and the path API.
-
base directory
Every API has an options argument that lets you define a baseDir that acts as the working directory of the operation.
In the above example the ~/avatars/tauri.png file is read since we are using the Home base directory.
-
path API
Alternatively you can use the path APIs to perform path manipulations.
Files
Create
Creates a file and returns a handle to it. If the file already exists, it is truncated.
Write
The plugin offers separate APIs for writing text and binary files for performance.
-
text files
-
binary files
Open
Opens a file and returns a handle to it. With this API you have more control over how the file should be opened (read-only mode, write-only mode, append instead of overwrite, only create if it does not exist, etc).
-
read-only
This is the default mode.
-
write-only
By default the file is truncated on any
file.write()
call. See the following example to learn how to append to the existing contents instead. -
append
Note that
{ append: true }
has the same effect as{ write: true, append: true }
. -
truncate
When the
truncate
option is set and the file already exists, it will be truncated to length 0.This option requires
write
to betrue
.You can use it along the
append
option if you want to rewrite an existing file using multiplefile.write()
calls. -
create
By default the
open
API only opens existing files. To create the file if it does not exist, opening it if it does, setcreate
totrue
:In order for the file to be created,
write
orappend
must also be set totrue
.To fail if the file already exists, see
createNew
. -
createNew
createNew
works similarly tocreate
, but if the file does not exist, the operation fails.In order for the file to be created,
write
must also be set totrue
.
Read
The plugin offers separate APIs for reading text and binary files for performance.
-
text files
If the file is large you can stream its lines with the
readTextFileLines
API: -
binary files
Remove
Call remove()
to delete a file. If the file does not exist, an error is returned.
Copy
The copyFile
function takes the source and destination paths.
Note that you must configure each base directory separately.
In the above example the <app-local-data>/user.db file is copied to $TMPDIR/user.db.bk.
Exists
Use the exists()
function to check if a file exists:
Metadata
File metadata can be retrieved with the stat
and the lstat
functions.
stat
follows symlinks (and returns an error if the actual file it points to is not allowed by the scope)
and lstat
does not follow symlinks, returning the information of the symlink itself.
Rename
The rename
function takes the source and destination paths.
Note that you must configure each base directory separately.
In the above example the <app-local-data>/user.db.bk file is renamed to $TMPDIR/user.db.
Truncate
Truncates or extends the specified file to reach the specified file length (defaults to 0).
- truncate to 0 length
- truncate to a specific length
Directories
Create
To create a directory, call the mkdir
function:
Read
The readDir
function recursively lists the entries of a directory:
Remove
Call remove()
to delete a directory. If the directory does not exist, an error is returned.
If the directory is not empty, the recursive
option must be set to true
:
Exists
Use the exists()
function to check if a directory exists:
Metadata
Directory metadata can be retrieved with the stat
and the lstat
functions.
stat
follows symlinks (and returns an error if the actual file it points to is not allowed by the scope)
and lstat
does not follow symlinks, returning the information of the symlink itself.
Watching changes
To watch a directory or file for changes, use the watch
or watchImmediate
functions.
-
watch
watch
is debounced so it only emits events after a certain delay: -
watchImmediate
watchImmediate
immediately notifies listeners of an event:
By default watch operations on a directory are not recursive.
Set the recursive
option to true
to recursively watch for changes on all sub-directories.
Permissions
By default all potentially dangerous plugin commands and scopes are blocked and cannot be accessed. You must modify the permissions in your capabilities
configuration to enable these.
See the Capabilities Overview for more information and the step by step guide to use plugin permissions.
Default Permission
This set of permissions describes the what kind of
file system access the fs
plugin has enabled or denied by default.
Granted Permissions
This default permission set enables read access to the application specific directories (AppConfig, AppData, AppLocalData, AppCache, AppLog) and all files and sub directories created in it. The location of these directories depends on the operating system, where the application is run.
In general these directories need to be manually created by the application at runtime, before accessing files or folders in it is possible.
Therefore, it is also allowed to create all of these folders via
the mkdir
command.
Denied Permissions
This default permission set prevents access to critical components of the Tauri application by default. On Windows the webview data folder access is denied.
Included permissions:
create-app-specific-dirs
read-app-specific-dirs-recursive
deny-default
Permission Table
Identifier | Description |
---|---|
|
This allows full recursive read access to the complete application folders, files and subdirectories. |
|
This allows full recursive write access to the complete application folders, files and subdirectories. |
|
This allows non-recursive read access to the application folders. |
|
This allows non-recursive write access to the application folders. |
|
This allows full recursive read access to metadata of the application folders, including file listing and statistics. |
|
This allows non-recursive read access to metadata of the application folders, including file listing and statistics. |
|
This scope permits recursive access to the complete application folders, including sub directories and files. |
|
This scope permits access to all files and list content of top level directories in the application folders. |
|
This scope permits to list all files and folders in the application directories. |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
This allows full recursive read access to the complete |
|
This allows full recursive write access to the complete |
|
This allows non-recursive read access to the |
|
This allows non-recursive write access to the |
|
This allows full recursive read access to metadata of the |
|
This allows non-recursive read access to metadata of the |
|
This scope permits recursive access to the complete |
|
This scope permits access to all files and list content of top level directories in the |
|
This scope permits to list all files and folders in the |
|
Enables the copy_file command without any pre-configured scope. |
|
Denies the copy_file command without any pre-configured scope. |
|
Enables the create command without any pre-configured scope. |
|
Denies the create command without any pre-configured scope. |
|
Enables the exists command without any pre-configured scope. |
|
Denies the exists command without any pre-configured scope. |
|
Enables the fstat command without any pre-configured scope. |
|
Denies the fstat command without any pre-configured scope. |
|
Enables the ftruncate command without any pre-configured scope. |
|
Denies the ftruncate command without any pre-configured scope. |
|
Enables the lstat command without any pre-configured scope. |
|
Denies the lstat command without any pre-configured scope. |
|
Enables the mkdir command without any pre-configured scope. |
|
Denies the mkdir command without any pre-configured scope. |
|
Enables the open command without any pre-configured scope. |
|
Denies the open command without any pre-configured scope. |
|
Enables the read command without any pre-configured scope. |
|
Denies the read command without any pre-configured scope. |
|
Enables the read_dir command without any pre-configured scope. |
|
Denies the read_dir command without any pre-configured scope. |
|
Enables the read_file command without any pre-configured scope. |
|
Denies the read_file command without any pre-configured scope. |
|
Enables the read_text_file command without any pre-configured scope. |
|
Denies the read_text_file command without any pre-configured scope. |
|
Enables the read_text_file_lines command without any pre-configured scope. |
|
Denies the read_text_file_lines command without any pre-configured scope. |
|
Enables the read_text_file_lines_next command without any pre-configured scope. |
|
Denies the read_text_file_lines_next command without any pre-configured scope. |
|
Enables the remove command without any pre-configured scope. |
|
Denies the remove command without any pre-configured scope. |
|
Enables the rename command without any pre-configured scope. |
|
Denies the rename command without any pre-configured scope. |
|
Enables the seek command without any pre-configured scope. |
|
Denies the seek command without any pre-configured scope. |
|
Enables the stat command without any pre-configured scope. |
|
Denies the stat command without any pre-configured scope. |
|
Enables the truncate command without any pre-configured scope. |
|
Denies the truncate command without any pre-configured scope. |
|
Enables the unwatch command without any pre-configured scope. |
|
Denies the unwatch command without any pre-configured scope. |
|
Enables the watch command without any pre-configured scope. |
|
Denies the watch command without any pre-configured scope. |
|
Enables the write command without any pre-configured scope. |
|
Denies the write command without any pre-configured scope. |
|
Enables the write_file command without any pre-configured scope. |
|
Denies the write_file command without any pre-configured scope. |
|
Enables the write_text_file command without any pre-configured scope. |
|
Denies the write_text_file command without any pre-configured scope. |
|
This permissions allows to create the application specific directories. |
|
This denies access to dangerous Tauri relevant files and folders by default. |
|
This denies read access to the
|
|
This denies read access to the
|
|
This enables all read related commands without any pre-configured accessible paths. |
|
This permission allows recursive read functionality on the application specific base directories. |
|
This enables directory read and file metadata related commands without any pre-configured accessible paths. |
|
This enables file read related commands without any pre-configured accessible paths. |
|
This enables all index or metadata related commands without any pre-configured accessible paths. |
|
An empty permission you can use to modify the global scope. |
|
This enables all write related commands without any pre-configured accessible paths. |
|
This enables all file write related commands without any pre-configured accessible paths. |
Scopes
This plugin permissions includes scopes for defining which paths are allowed or explicitly rejected. For more information on scopes, see the Command Scopes.
Each allow
or deny
scope must include an array listing all paths that should be allowed or denied.
The scope entries are in the { path: string }
format.
Scope entries can use $<path>
variables to reference common system paths such as the home directory,
the app resources directory and the config directory. The following table lists all common paths you can reference:
Path | Variable |
---|---|
appConfigDir | $APPCONFIG |
appDataDir | $APPDATA |
appLocalDataDir | $APPLOCALDATA |
appcacheDir | $APPCACHE |
applogDir | $APPLOG |
audioDir | $AUDIO |
cacheDir | $CACHE |
configDir | $CONFIG |
dataDir | $DATA |
localDataDir | $LOCALDATA |
desktopDir | $DESKTOP |
documentDir | $DOCUMENT |
downloadDir | $DOWNLOAD |
executableDir | $EXE |
fontDir | $FONT |
homeDir | $HOME |
pictureDir | $PICTURE |
publicDir | $PUBLIC |
runtimeDir | $RUNTIME |
templateDir | $TEMPLATE |
videoDir | $VIDEO |
resourceDir | $RESOURCE |
tempDir | $TEMP |
Examples
- global scope
To apply a scope to any fs
command, use the fs:scope
permission:
To apply a scope to a specific fs
command,
use the the object form of permissions { "identifier": string, "allow"?: [], "deny"?: [] }
:
In the above example you can use the exists
API using any $APPDATA
sub path (does not include sub-directories)
and the rename
© 2024 Tauri Contributors. CC-BY / MIT