mirror of https://github.com/tauri-apps/tauri-docs.git synced 2026-01-31 00:35:16 +01:00

Files

tauri 856fa302d0 Update Docs (#3409 )

Co-authored-by: tauri-bot <tauri-bot@users.noreply.github.com>

2025-07-22 12:14:51 +02:00

22 KiB

Raw Permalink Blame History

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

Name	Type	Defined in
`App`	`18`	fs.ts:98
`AppCache`	`24`	fs.ts:104
`AppConfig`	`21`	fs.ts:101
`AppData`	`22`	fs.ts:102
`AppLocalData`	`23`	fs.ts:103
`AppLog`	`25`	fs.ts:105
`Audio`	`1`	fs.ts:81
`Cache`	`2`	fs.ts:82
`Config`	`3`	fs.ts:83
`Data`	`4`	fs.ts:84
`Desktop`	`6`	fs.ts:86
`Document`	`7`	fs.ts:87
`Download`	`8`	fs.ts:88
`Executable`	`9`	fs.ts:89
`Font`	`10`	fs.ts:90
`Home`	`11`	fs.ts:91
`LocalData`	`5`	fs.ts:85
`Log`	`19`	fs.ts:99
`Picture`	`12`	fs.ts:92
`Public`	`13`	fs.ts:93
`Resource`	`17`	fs.ts:97
`Runtime`	`14`	fs.ts:94
`Temp`	`20`	fs.ts:100
`Template`	`15`	fs.ts:95
`Video`	`16`	fs.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:167

`name`

Optional name: string

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

Defined in: fs.ts:165

`path`

path: string

Defined in: fs.ts:160

`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:153

`path`

path: string

Path to the file to write.

Defined in: fs.ts:151

`FsDirOptions`

Since: 1.0.0

Properties

`dir`

Optional dir: BaseDirectory

Defined in: fs.ts:126

`recursive`

Optional recursive: boolean

Defined in: fs.ts:127

`FsOptions`

Since: 1.0.0

Properties

`append`

Optional append: boolean

Whether the content should overwrite the content of the file or append to it.

Since: 1.5.0

Defined in: fs.ts:118

`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:139

`path`

path: string

Path to the file to write.

Defined in: fs.ts:137

Type Aliases

`BinaryFileContents`

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

Defined in: fs.ts:142

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

Name	Type
`source`	`string`
`destination`	`string`
`options`	`FsOptions`

**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

Name	Type
`dir`	`string`
`options`	`FsDirOptions`

**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

Name	Type
`path`	`string`
`options`	`FsOptions`

**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

Name	Type
`filePath`	`string`
`options`	`FsOptions`

**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

Name	Type
`dir`	`string`
`options`	`FsDirOptions`

**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

Name	Type
`filePath`	`string`
`options`	`FsOptions`

**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

Name	Type
`dir`	`string`
`options`	`FsDirOptions`

**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

Name	Type
`file`	`string`
`options`	`FsOptions`

**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

Name	Type
`oldPath`	`string`
`newPath`	`string`
`options`	`FsOptions`

**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

Name	Type	Description
`path`	`string`	-
`contents`	`BinaryFileContents`	-
`options?`	`FsOptions`	Configuration 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

Name	Type	Description
`file`	`FsBinaryFileOption`	The object containing the file path and contents.
`options?`	`FsOptions`	Configuration 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

Name	Type
`path`	`string`
`contents`	`string`
`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

Name	Type
`file`	`FsTextFileOption`
`options?`	`FsOptions`

**Returns: **Promise<void>

A promise indicating the success or failure of the operation.

22 KiB Raw Permalink Blame History

fs

Security

References

Dir

writeFile

Enumerations

BaseDirectory

Enumeration Members

Interfaces

FileEntry

Properties

children

name

path

FsBinaryFileOption

Properties

contents

path

FsDirOptions

Properties

dir

recursive

FsOptions

Properties

append

dir

FsTextFileOption

Properties

contents

path

Type Aliases

BinaryFileContents

Functions

copyFile

createDir

exists

readBinaryFile

readDir

readTextFile

removeDir

removeFile

renameFile

writeBinaryFile

writeTextFile

22 KiB

Raw Permalink Blame History

`Dir`

`writeFile`

`BaseDirectory`

`FileEntry`

`children`

`name`

`path`

`FsBinaryFileOption`

`contents`

`path`

`FsDirOptions`

`dir`

`recursive`

`FsOptions`

`append`

`dir`

`FsTextFileOption`

`contents`

`path`

`BinaryFileContents`

`copyFile`

`createDir`

`exists`

`readBinaryFile`

`readDir`

`readTextFile`

`removeDir`

`removeFile`

`renameFile`

`writeBinaryFile`

`writeTextFile`