skip to content

In expo-file-system, what is the difference between Paths.document and Paths.cache, and which files belong in each?

level: juniorimportance: must knowfreq 52%

answer

  1. two sandbox folders, two promises
  2. one may be purged when storage runs low
  3. re-downloadable data goes in cache
  4. irreplaceable user data goes in document
  5. both vanish on uninstall

basics

~20 s

Paths.document is the app's persistent documents directory, which the system does not clear on its own; Paths.cache is the caches directory, which the OS may purge when storage runs low. Keep irreplaceable data in document and re-creatable data in cache.

solid answer

~40 s

`expo-file-system` exposes the app sandbox through the static `Paths` class, and each getter returns a `Directory` object. `Paths.document` maps to the iOS `Documents` folder and the Android internal files directory; the library describes it as safe from deletion by the system, so files stay until the app deletes them or the user uninstalls. `Paths.cache` maps to the caches directory, which the OS may empty when the device is low on storage, at a moment the app does not choose. So I put user-created or user-requested content that cannot be recreated offline in `document`, and anything I can download or regenerate, such as browsed map tiles or thumbnails, in `cache`, and every read from `cache` must handle a missing file.

code

typescript · 12 lines
typescript
import { Directory, File, Paths } from 'expo-file-system';

const tileCache = new Directory(Paths.cache, 'tiles');
const savedRegions = new Directory(Paths.document, 'offline-regions');

tileCache.create({ intermediates: true, idempotent: true });
savedRegions.create({ intermediates: true, idempotent: true });

export function cachedTile(z: number, x: number, y: number): File | null {
  const tile = new File(tileCache, `${z}-${x}-${y}.png`);
  return tile.exists ? tile : null; // the OS may have purged it
}

go deeper

for a junior

Recall the contract: document is kept until the app deletes it, cache may be purged by the OS under storage pressure, and both disappear on uninstall.

for a middle

Explain the decision rule of whether the app can recreate the file without the user, and show defensive reads from the cache with file.exists and a network fallback.

for a senior

Show judgement on edge cases such as user-requested offline regions that are re-downloadable in principle but belong in document, and who owns cleanup of each directory.

for a principal

Frame storage as a product promise: which data the user expects to survive offline and after storage pressure, and how the app communicates and lets the user reclaim that space.

## What the two directories are Every iOS and Android app runs in a **sandbox**: a private area of storage that only that app can read and write. `expo-file-system` exposes the useful locations through the static **`Paths`** class (`import { Paths } from 'expo-file-system'`). Each getter returns a `Directory` object, not a string: - **`Paths.document`** is the app's documents directory: the `Documents` folder on iOS and the app's internal files directory on Android. The library documents it as a place for files that are safe from being deleted by the system. - **`Paths.cache`** is the app's caches directory. The library documents it as a place for files that can be deleted by the system when the device runs low on storage. - **`Paths.bundle`** is where assets shipped inside the app binary live. It is something to read from, not a place to save downloads. The difference between the first two is a **contract with the operating system**, not a difference in speed or format. Both are ordinary folders on the same disk; only one of them may be emptied behind the app's back. ## Side by side | | `Paths.document` | `Paths.cache` | |---|---|---| | Cleared by the OS under storage pressure | No | Yes, possibly without warning | | Survives an app restart | Yes | Yes, unless purged meanwhile | | Removed when the app is uninstalled | Yes | Yes | | Included in iOS device backups | Yes | No | | Who is responsible for cleanup | The app, always | The app, with the OS as a last resort | | Typical contents | drafts, user exports, offline regions the user asked for | browsed tiles, thumbnails, temporary exports | A common misconception is that the cache directory is a temp folder emptied on every launch. It is not: files there persist across restarts and usually across updates. What changes is who may delete them. ## The one question that picks the directory Ask: **"If this file vanished right now, could the app get it back without the user's help?"** 1. If yes, because the file is a copy of something on a server or can be regenerated, it belongs in `Paths.cache`. 2. If no, because the user created it or explicitly asked to keep it, it belongs in `Paths.document`. The offline-map scenario shows the nuance. Tiles fetched while the user pans around a map are a pure cache: losing them costs a re-download. A region the user tapped **"save for offline use"** before a hike is different: it is re-downloadable in principle but not at the moment of need, in a valley without signal. That pack belongs in `document`, and the app owns its lifecycle, offering a "remove offline region" action. ## Consequences for the code - **Treat every read from the cache as optional.** Check `file.exists` (a synchronous property) or catch the error, and fall back to the network. - **The document directory never shrinks by itself.** Anything written there counts as the app's data in the system storage settings until the app deletes it. - **Build paths with the constructors.** `new File(Paths.cache, 'tiles', '12-2048-1361.png')` joins the segments; creating the object does not touch the disk. - **Check free space before a large download.** `Paths.availableDiskSpace` and `Paths.totalDiskSpace` report bytes on the device's internal storage. - **Exposing documents to the user is opt-in.** On iOS the `Documents` folder appears in the Files app only when the `expo-file-system` config plugin's `enableFileSharing` option is set and a new binary is built. ## Version notes The `Paths`, `File` and `Directory` object API became the default export of `expo-file-system` in SDK 54. Older code uses the string constants `documentDirectory` and `cacheDirectory` (each ending in `/`), which now come only from `expo-file-system/legacy`. In Expo Go on Android, `Paths.cache` and `Paths.document` point to directories isolated per project; a development or production build uses the app's own directories.

  • Does a file in Paths.cache survive an app restart?
    Yes. The caches directory is not emptied on launch; files persist across restarts and normally across updates. The only difference from `Paths.document` is that the OS may remove cache contents when storage runs low, at a time the app does not control, so the code must tolerate a missing file.
  • How can an iOS user see files the app saved to Paths.document?
    Only if the app opts in. The `expo-file-system` config plugin's `enableFileSharing` option sets `UIFileSharingEnabled` in Info.plist, which makes the Documents folder visible in the Files app. It is a native setting, so it needs a new build, not an over-the-air update.

Paths.document is a locked desk drawer: only you empty it. Paths.cache is a shared whiteboard the cleaners may wipe when the office runs out of space, so anything written there must be easy to write again.

  • The cache directory is emptied every time the app restarts.
  • Files in the document directory survive uninstalling the app.
  • The OS frees space by deleting old files from the document directory.
  • Paths.bundle is a good place to save downloaded files.
  • Cache and document differ in read speed, so pick by performance.

Expo SDK 57 (expo-file-system 57.x). The Paths/File/Directory object API is the default since SDK 54; the documentDirectory and cacheDirectory string constants live in expo-file-system/legacy.