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

# File utilities

> Utility functions for working with files in Kotlin Multiplatform

## Standard Directories

<Check>Supported on Android, iOS, macOS, JVM, and Kotlin/Native Linux targets</Check>

FileKit provides access to standard platform-specific directories:

```kotlin theme={null}
// Get the application's files directory
val filesDir: PlatformFile = FileKit.filesDir

// Get the application's cache directory
val cacheDir: PlatformFile = FileKit.cacheDir

// Get the application's databases directory
val databasesDir: PlatformFile = FileKit.databasesDir
```

These directories are automatically created if they don't exist and are properly sandboxed on each platform.

### Platform-specific Directory Behavior

Each platform maps these standard directories to different locations according to platform conventions:

**Android**

* **filesDir**: Maps to `context.filesDir`, which is the app's private internal storage
* **cacheDir**: Maps to `context.cacheDir`, which is the app's private cache directory
* **databasesDir**: Maps to a `databases` subdirectory in the app's internal storage

**iOS**

* **filesDir**: Maps to the app's Documents directory, which is backed up with iCloud
* **cacheDir**: Maps to the app's Caches directory, which isn't backed up and may be cleared by the system
* **databasesDir**: Maps to a `databases` subdirectory in the app's Documents directory

**macOS**

* **filesDir**: Maps to `~/Library/Application Support/<app-id>/`, requiring FileKit initialization with an app ID
* **cacheDir**: Maps to `~/Library/Caches/<app-id>/`
* **databasesDir**: Maps to a `databases` subdirectory in the application support directory

**JVM (Desktop)**

* **filesDir**: Maps to platform-specific app data locations:
  * Linux: `~/.local/share/<app-id>/`
  * macOS: `~/Library/Application Support/<app-id>/`
  * Windows: `%APPDATA%/<app-id>/`
* **cacheDir**: Maps to platform-specific cache locations:
  * Linux: `~/.cache/<app-id>/`
  * macOS: `~/Library/Caches/<app-id>/`
  * Windows: `%LOCALAPPDATA%/<app-id>/Cache/`
* **databasesDir**: Maps to a `databases` subdirectory within filesDir

**Kotlin/Native Linux (`linuxX64`, `linuxArm64`)**

* **filesDir**: Maps to `$XDG_DATA_HOME/<app-id>/`, or `~/.local/share/<app-id>/` when `XDG_DATA_HOME` is unset
* **cacheDir**: Maps to `$XDG_CACHE_HOME/<app-id>/`, or `~/.cache/<app-id>/` when `XDG_CACHE_HOME` is unset
* **databasesDir**: Maps to a `databases` subdirectory within filesDir

<Note>
  On JVM, macOS, and Kotlin/Native Linux platforms, you must initialize FileKit with an application ID before accessing these directories. See the [Setup guide](/core/setup) for details.
</Note>

### Additional Directories

On desktop platforms (JVM, macOS, and Kotlin/Native Linux), FileKit provides access to common user directories:

```kotlin theme={null}
// Typed API
val downloads: PlatformFile = FileKit.userDirectory(FileKitUserDirectory.Downloads)
val pictures: PlatformFile = FileKit.userDirectory(FileKitUserDirectory.Pictures)
val videos: PlatformFile = FileKit.userDirectory(FileKitUserDirectory.Videos)
val music: PlatformFile = FileKit.userDirectory(FileKitUserDirectory.Music)
val documents: PlatformFile = FileKit.userDirectory(FileKitUserDirectory.Documents)

// Convenience wrappers
val downloadsDir: PlatformFile = FileKit.downloadsDir
val picturesDir: PlatformFile = FileKit.picturesDir
val videosDir: PlatformFile = FileKit.videosDir
val musicDir: PlatformFile = FileKit.musicDir
val documentsDir: PlatformFile = FileKit.documentsDir
```

Use `FileKit.userDirectoryOrNull(...)` when you prefer nullable handling instead of exceptions.

### Directory Usage Example

````kotlin theme={null}
// Store app configuration
val configFile = FileKit.filesDir / "config.json"
configFile.writeString("{\"version\": 1}")

// Store temporary processing data
val tempFile = FileKit.cacheDir / "temp_data.bin"
tempFile.write(processingData)

```kotlin
// Access a database file
val dbFile = FileKit.databasesDir / "app.db" 
// Use the database file with your preferred database library
````

## Scoped Resource Access (iOS/macOS)

On iOS and macOS, some files may require security-scoped access to be read or written. FileKit provides utilities to manage this:

```kotlin theme={null}
// Start accessing a security-scoped resource
val success = platformFile.startAccessingSecurityScopedResource()
if (success) {
    try {
        // Perform file operations
    } finally {
        // Stop accessing the resource
        platformFile.stopAccessingSecurityScopedResource()
    }
}
```

To simplify this pattern, you can use the `withScopedAccess` method:

```kotlin theme={null}
platformFile.withScopedAccess { file ->
    // Perform file operations with scoped access
}
```

These methods ensure that security-scoped resources are properly accessed and released, preventing potential resource leaks.

## Downloading files from web

<Check>Supported on JS and WASM targets</Check>

FileKit provides a convenient way to download files in web environments (JS and WASM targets). This functionality allows users to save files from your web application to their local device:

```kotlin theme={null}
// Download from bytes
FileKit.download(bytes, "file.txt")

// Download from file
val file: PlatformFile = ...
FileKit.download(file, "file.txt")
```