> ## Documentation Index
> Fetch the complete documentation index at: https://configurate.crystaworld.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Rust Plugin Builder: Configure tauri-plugin-configurate

> Reference for the tauri-plugin-configurate Rust Builder API: customize read byte limits, BaseDirectory allowlists, and register the plugin with Tauri.

The `Builder` struct lets you configure `tauri-plugin-configurate` before it is registered with Tauri. Use it to set a custom file-size cap, restrict which `BaseDirectory` values IPC payloads may reference, or open that restriction entirely. If you do not need any customization, the `init()` shorthand registers the plugin with all defaults.

## Initializing the plugin

You have two ways to register the plugin with `tauri::Builder`.

**Simple initialization** — uses every default setting and is the most common choice:

```rust theme={null}
tauri::Builder::default()
    .plugin(tauri_plugin_configurate::init())
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
```

**Custom initialization** — chain builder methods before calling `.build()` to override specific defaults:

```rust theme={null}
tauri::Builder::default()
    .plugin(
        tauri_plugin_configurate::Builder::default()
            .max_read_bytes(32 * 1024 * 1024)
            .build()
    )
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
```

<Note>
  `init()` is exactly equivalent to `Builder::default().build()`. Prefer `init()` when you have nothing to customize — it is shorter and signals intent clearly.
</Note>

## Builder methods

### `Builder::default()` / `Builder::new()`

Creates a new builder pre-loaded with the following defaults:

| Setting             | Default value                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------- |
| `max_read_bytes`    | `16_777_216` (16 MiB)                                                                         |
| `allowed_base_dirs` | App-scoped directories only (see [Default allowed directories](#default-allowed-directories)) |

Both functions are interchangeable — `Builder::new()` delegates to `Builder::default()`.

```rust theme={null}
let plugin = tauri_plugin_configurate::Builder::default().build();
// equivalent to:
let plugin = tauri_plugin_configurate::Builder::new().build();
```

***

### `.max_read_bytes(bytes: usize) -> Self`

<ParamField path="bytes" type="usize" required>
  Maximum number of bytes the plugin will read from a single config file or import content string. Must be greater than zero.
</ParamField>

Sets the upper bound on how many bytes the plugin reads when loading a config file or processing an import payload. Any read that would exceed this limit is rejected with an error before the full content is consumed, protecting your application from unexpectedly large files.

The default is **16 MiB** (`16_777_216` bytes). Raise this if your app legitimately works with large configs; lower it for tighter memory constraints.

```rust theme={null}
.max_read_bytes(32 * 1024 * 1024) // 32 MiB
```

<Warning>
  `max_read_bytes` must be greater than `0`. Passing `0` causes the plugin to panic during initialization with the message `"maxReadBytes must be greater than 0"`.
</Warning>

**`tauri.conf.json` takes precedence.** When `plugins.configurate.maxReadBytes` is set in your Tauri config file, that value overrides whatever you pass to `.max_read_bytes()` at runtime. See [tauri.conf.json configuration](#tauriconfjson-configuration) below.

***

### `.allowed_base_directories(dirs) -> Self`

<ParamField path="dirs" type="impl IntoIterator<Item = BaseDirectory>" required>
  An iterable of `tauri::path::BaseDirectory` variants that IPC payloads are permitted to use. Replaces the default allowlist entirely.
</ParamField>

Replaces the default `BaseDirectory` allowlist with your own set. Any IPC request that references a directory not in this list is rejected by the plugin before touching the filesystem.

Use this method when your application genuinely needs access to a directory outside the app-scoped defaults — for example, `Document` for user-facing export paths — but you still want to keep the allowlist explicit rather than unrestricted.

```rust theme={null}
.allowed_base_directories([
    tauri::path::BaseDirectory::AppConfig,
    tauri::path::BaseDirectory::Document,
])
```

***

### `.allow_any_base_directory() -> Self`

Disables `BaseDirectory` validation entirely. After calling this method, IPC payloads may reference any `BaseDirectory` variant without restriction.

```rust theme={null}
.allow_any_base_directory()
```

Use this only when your use case genuinely requires arbitrary directory access — for example, a developer tool that must navigate the user's home tree. For production apps that manage their own config files, the default restricted policy is strongly recommended.

***

### `.build() -> TauriPlugin`

Consumes the builder and returns the configured `TauriPlugin` instance ready to pass to `.plugin()`. Call this as the final step of every builder chain.

```rust theme={null}
let plugin = tauri_plugin_configurate::Builder::default()
    .max_read_bytes(8 * 1024 * 1024)
    .build();

tauri::Builder::default()
    .plugin(plugin)
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
```

## Default allowed directories

When you use `Builder::default()`, `Builder::new()`, or `init()`, the plugin restricts IPC `baseDir` values to the following app-scoped and system temporary directories:

| `BaseDirectory` variant | Typical resolved path                     |
| ----------------------- | ----------------------------------------- |
| `AppConfig`             | Platform app config folder                |
| `AppData`               | Platform app data folder                  |
| `AppLocalData`          | Platform app local-data folder            |
| `AppCache`              | Platform app cache folder                 |
| `AppLog`                | Platform app log folder                   |
| `Resource`              | Tauri resource directory (bundled assets) |
| `Temp`                  | System temporary directory                |

Any IPC request that references a directory outside this list — such as `Home`, `Desktop`, or `Download` — is rejected with an error describing which directories are permitted. Use `.allowed_base_directories()` or `.allow_any_base_directory()` on the builder to expand access.

## `tauri.conf.json` configuration

You can set `maxReadBytes` in your Tauri project's `tauri.conf.json` file under the `plugins.configurate` key:

```json theme={null}
{
  "plugins": {
    "configurate": {
      "maxReadBytes": 33554432
    }
  }
}
```

When this key is present, its value **overrides** any value you pass to `.max_read_bytes()` in the Rust builder. This makes it straightforward to tune the limit for different build profiles (for example, a CI environment config that keeps the limit low) without changing source code.

The `BaseDirectory` allowlist is **not** configurable through `tauri.conf.json` — use the builder methods for that.