跳到主要内容

fs

Access the file system.

This package is also accessible with window.__TAURI__.fs when build.withGlobalTauri in tauri.conf.json is set to true.

The APIs must be added to tauri.allowlist.fs in tauri.conf.json:

{
  "tauri": {
    "allowlist": {
      "fs": {
        "all": true, // enable all FS APIs
        "readFile": true,
        "writeFile": true,
        "readDir": true,
        "copyFile": true,
        "createDir": true,
        "removeDir": true,
        "removeFile": true,
        "renameFile": true,
        "exists": true
      }
    }
  }
}

It is recommended to allowlist only the APIs you use for optimal bundle size and security.

Security​

This module prevents path traversal, not allowing absolute paths or parent dir components (i.e. "/usr/path/to/file" or "../path/to/file" paths are not allowed). Paths accessed with this API must be relative to one of the base directories so if you need access to arbitrary filesystem paths, you must write such logic on the core layer instead.

The API has a scope configuration that forces you to restrict the paths that can be accessed using glob patterns.

The scope configuration is an array of glob patterns describing folder paths that are allowed. For instance, this scope configuration only allows accessing files on the databases folder of the $APPDATA directory:

{
  "tauri": {
    "allowlist": {
      "fs": {
        "scope": ["$APPDATA/databases/*"]
      }
    }
  }
}

Notice the use of the $APPDATA variable. The value is injected at runtime, resolving to the app data directory. The available variables are: $APPCONFIG, $APPDATA, $APPLOCALDATA, $APPCACHE, $APPLOG, $AUDIO, $CACHE, $CONFIG, $DATA, $LOCALDATA, $DESKTOP, $DOCUMENT, $DOWNLOAD, $EXE, $FONT, $HOME, $PICTURE, $PUBLIC, $RUNTIME, $TEMPLATE, $VIDEO, $RESOURCE, $APP, $LOG, $TEMP.

Trying to execute any API with a URL not configured on the scope results in a promise rejection due to denied access.

Note that this scope applies to all APIs on this module.

References​

Dir​

Renames and re-exports BaseDirectory

writeFile​

Renames and re-exports writeTextFile

Enumerations​

BaseDirectory​

Since: 1.0.0

Enumeration Members​

NameTypeDefined in
18fs.ts:98
24fs.ts:104
21fs.ts:101
22fs.ts:102
23fs.ts:103
25fs.ts:105
1fs.ts:81
2fs.ts:82
3fs.ts:83
4fs.ts:84
6fs.ts:86
7fs.ts:87
8fs.ts:88
9fs.ts:89
10fs.ts:90
11fs.ts:91
5fs.ts:85
19fs.ts:99
12fs.ts:92
13fs.ts:93
17fs.ts:97
14fs.ts:94
20fs.ts:100
15fs.ts:95
16fs.ts:96

Interfaces​

FileEntry​

Since: 1.0.0

Properties​

children​

Optional children: FileEntry[]

Children of this entry if it's a directory; null otherwise

Defined in: fs.ts:161

name​

Optional name: string

Name of the directory/file can be null if the path terminates with ..

Defined in: fs.ts:159

path​

path: string

Defined in: fs.ts:154

FsBinaryFileOption​

Options object used to write a binary data to a file.

Since: 1.0.0

Properties​

contents​

contents: BinaryFileContents

The byte array contents.

Defined in: fs.ts:147

path​

path: string

Path to the file to write.

Defined in: fs.ts:145

FsDirOptions​

Since: 1.0.0

Properties​

dir​

Optional dir: BaseDirectory

Defined in: fs.ts:120

recursive​

Optional recursive: boolean

Defined in: fs.ts:121

FsOptions​

Since: 1.0.0

Properties​

dir​

Optional dir: BaseDirectory

Defined in: fs.ts:112

FsTextFileOption​

Options object used to write a UTF-8 string to a file.

Since: 1.0.0

Properties​

contents​

contents: string

The UTF-8 string to write to the file.

Defined in: fs.ts:133

path​

path: string

Path to the file to write.

Defined in: fs.ts:131

Type Aliases​

BinaryFileContents​

BinaryFileContents: Iterable<number> | ArrayLike<number> | ArrayBuffer

Defined in: fs.ts:136

Functions​

copyFile​

copyFile(source: string, destination: string, options?: FsOptions): Promise<void>

Copies a file to a destination.

Example

import { copyFile, BaseDirectory } from '@tauri-apps/api/fs';
// Copy the `$APPCONFIG/app.conf` file to `$APPCONFIG/app.conf.bk`
await copyFile('app.conf', 'app.conf.bk', { dir: BaseDirectory.AppConfig });

Since: 1.0.0

Parameters

NameType
sourcestring
destinationstring
optionsFsOptions

Returns: Promise<void>

A promise indicating the success or failure of the operation.

createDir​

createDir(dir: string, options?: FsDirOptions): Promise<void>

Creates a directory. If one of the path's parent components doesn't exist and the recursive option isn't set to true, the promise will be rejected.

Example

import { createDir, BaseDirectory } from '@tauri-apps/api/fs';
// Create the `$APPDATA/users` directory
await createDir('users', { dir: BaseDirectory.AppData, recursive: true });

Since: 1.0.0

Parameters

NameType
dirstring
optionsFsDirOptions

Returns: Promise<void>

A promise indicating the success or failure of the operation.

exists​

exists(path: string, options?: FsOptions): Promise<boolean>

Check if a path exists.

Example

import { exists, BaseDirectory } from '@tauri-apps/api/fs';
// Check if the `$APPDATA/avatar.png` file exists
await exists('avatar.png', { dir: BaseDirectory.AppData });

Since: 1.1.0

Parameters

NameType
pathstring
optionsFsOptions

Returns: Promise<boolean>

readBinaryFile​

readBinaryFile(filePath: string, options?: FsOptions): Promise<Uint8Array>

Reads a file as byte array.

Example

import { readBinaryFile, BaseDirectory } from '@tauri-apps/api/fs';
// Read the image file in the `$RESOURCEDIR/avatar.png` path
const contents = await readBinaryFile('avatar.png', { dir: BaseDirectory.Resource });

Since: 1.0.0

Parameters

NameType
filePathstring
optionsFsOptions

Returns: Promise<Uint8Array>

readDir​

readDir(dir: string, options?: FsDirOptions): Promise<FileEntry[]>

List directory files.

Example

import { readDir, BaseDirectory } from '@tauri-apps/api/fs';
// Reads the `$APPDATA/users` directory recursively
const entries = await readDir('users', { dir: BaseDirectory.AppData, recursive: true });

function processEntries(entries) {
  for (const entry of entries) {
    console.log(`Entry: ${entry.path}`);
    if (entry.children) {
      processEntries(entry.children)
    }
  }
}

Since: 1.0.0

Parameters

NameType
dirstring
optionsFsDirOptions

Returns: Promise<FileEntry[]>

readTextFile​

readTextFile(filePath: string, options?: FsOptions): Promise<string>

Reads a file as an UTF-8 encoded string.

Example

import { readTextFile, BaseDirectory } from '@tauri-apps/api/fs';
// Read the text file in the `$APPCONFIG/app.conf` path
const contents = await readTextFile('app.conf', { dir: BaseDirectory.AppConfig });

Since: 1.0.0

Parameters

NameType
filePathstring
optionsFsOptions

Returns: Promise<string>

removeDir​

removeDir(dir: string, options?: FsDirOptions): Promise<void>

Removes a directory. If the directory is not empty and the recursive option isn't set to true, the promise will be rejected.

Example

import { removeDir, BaseDirectory } from '@tauri-apps/api/fs';
// Remove the directory `$APPDATA/users`
await removeDir('users', { dir: BaseDirectory.AppData });

Since: 1.0.0

Parameters

NameType
dirstring
optionsFsDirOptions

Returns: Promise<void>

A promise indicating the success or failure of the operation.

removeFile​

removeFile(file: string, options?: FsOptions): Promise<void>

Removes a file.

Example

import { removeFile, BaseDirectory } from '@tauri-apps/api/fs';
// Remove the `$APPConfig/app.conf` file
await removeFile('app.conf', { dir: BaseDirectory.AppConfig });

Since: 1.0.0

Parameters

NameType
filestring
optionsFsOptions

Returns: Promise<void>

A promise indicating the success or failure of the operation.

renameFile​

renameFile(oldPath: string, newPath: string, options?: FsOptions): Promise<void>

Renames a file.

Example

import { renameFile, BaseDirectory } from '@tauri-apps/api/fs';
// Rename the `$APPDATA/avatar.png` file
await renameFile('avatar.png', 'deleted.png', { dir: BaseDirectory.AppData });

Since: 1.0.0

Parameters

NameType
oldPathstring
newPathstring
optionsFsOptions

Returns: Promise<void>

A promise indicating the success or failure of the operation.

writeBinaryFile​

writeBinaryFile(path: string, contents: BinaryFileContents, options?: FsOptions): Promise<void>

Writes a byte array content to a file.

Example

import { writeBinaryFile, BaseDirectory } from '@tauri-apps/api/fs';
// Write a binary file to the `$APPDATA/avatar.png` path
await writeBinaryFile('avatar.png', new Uint8Array([]), { dir: BaseDirectory.AppData });

Since: 1.0.0

Parameters

NameTypeDescription
pathstring-
contentsBinaryFileContents-
options?FsOptionsConfiguration object.

Returns: Promise<void>

A promise indicating the success or failure of the operation.

writeBinaryFile(file: FsBinaryFileOption, options?: FsOptions): Promise<void>

Writes a byte array content to a file.

Example

import { writeBinaryFile, BaseDirectory } from '@tauri-apps/api/fs';
// Write a binary file to the `$APPDATA/avatar.png` path
await writeBinaryFile({ path: 'avatar.png', contents: new Uint8Array([]) }, { dir: BaseDirectory.AppData });

Since: 1.0.0

Parameters

NameTypeDescription
fileFsBinaryFileOptionThe object containing the file path and contents.
options?FsOptionsConfiguration object.

Returns: Promise<void>

A promise indicating the success or failure of the operation.

writeTextFile​

writeTextFile(path: string, contents: string, options?: FsOptions): Promise<void>

Writes a UTF-8 text file.

Example

import { writeTextFile, BaseDirectory } from '@tauri-apps/api/fs';
// Write a text file to the `$APPCONFIG/app.conf` path
await writeTextFile('app.conf', 'file contents', { dir: BaseDirectory.AppConfig });

Since: 1.0.0

Parameters

NameType
pathstring
contentsstring
options?FsOptions

Returns: Promise<void>

writeTextFile(file: FsTextFileOption, options?: FsOptions): Promise<void>

Writes a UTF-8 text file.

Example

import { writeTextFile, BaseDirectory } from '@tauri-apps/api/fs';
// Write a text file to the `$APPCONFIG/app.conf` path
await writeTextFile({ path: 'app.conf', contents: 'file contents' }, { dir: BaseDirectory.AppConfig });

Since: 1.0.0

Parameters

NameType
fileFsTextFileOption
options?FsOptions

Returns: Promise<void>

A promise indicating the success or failure of the operation.