expo-file-system

Q: Como instalo o expo-file-system no SDK 57?

Importe { File, Directory, Paths } de expo-file-system - não apenas o namespace padrão.

Q: Quando devo usar cache vs document?

cache - downloads reproduzíveis, miniaturas, processamento temporário. document - exportações criadas pelo usuário que o aplicativo não deve excluir silenciosamente.

Caminhos com sandbox, downloads e migração da API FS legada - o cookbook expo-file-system para aplicativos Expo SDK 57 que armazenam PDFs, fotos e payloads offline no dispositivo.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

npx expo install expo-file-system

import { Directory, File, Paths } from "expo-file-system";
 
export function ensureDownloadDir() {
  const dir = new Directory(Paths.cache, "downloads");
  if (!dir.exists) {
    dir.create();
  }
  return dir;
}
 
export async function downloadPdf(url: string, filename: string) {
  const dir = ensureDownloadDir();
  const output = await File.downloadFileAsync(url, dir);
  return output.uri;
}
 
export function writeJsonCache(name: string, data: unknown) {
  const file = new File(Paths.cache, `${name}.json`);
  if (!file.exists) {
    file.create();
  }
  file.write(JSON.stringify(data));
}

Quando usar isso:

Cache de respostas de API ou PDFs para leitura offline.
Persistência de fotos geradas pelo usuário antes do upload em segundo plano.
Leitura de ativos empacotados copiados para o cache gravável.
Upload de arquivos com progresso File.createUploadTask.

Quando evitar:

Segredos e tokens - use expo-secure-store.
Dados relacionais estruturados - use SQLite; armazene apenas caminhos.
Reprodução de mídia de streaming de grande porte - considere caches de mídia dedicados/CDN.

Exemplo de Trabalho

Download com progresso, metadados JSON auxiliares e interoperabilidade legada durante a migração.

npx expo install expo-file-system

// src/files/downloadWithProgress.ts
import { Directory, File, Paths } from "expo-file-system";
 
export async function downloadInspectionPdf(
  url: string,
  jobId: string,
  onProgress: (ratio: number) => void
) {
  const dir = new Directory(Paths.document, "inspections", jobId);
  if (!dir.exists) {
    dir.create({ intermediates: true });
  }
 
  const destination = new File(dir, "report.pdf");
  const task = File.createDownloadTask(url, destination, {
    onProgress: ({ bytesWritten, totalBytes }) => {
      if (totalBytes > 0) {
        onProgress(bytesWritten / totalBytes);
      }
    },
  });
 
  const file = await task.downloadAsync();
  if (!file) throw new Error("Download paused or cancelled");
 
  const meta = new File(dir, "meta.json");
  meta.create();
  meta.write(JSON.stringify({ url, downloadedAt: Date.now() }));
 
  return file.uri;
}

// src/files/listInspections.ts
import { Directory, Paths } from "expo-file-system";
 
export function listInspectionJobIds(): string[] {
  const root = new Directory(Paths.document, "inspections");
  if (!root.exists) return [];
 
  return root
    .list()
    .filter((entry) => entry instanceof Directory)
    .map((d) => d.name);
}

// src/files/legacyRead.ts - ponte temporária
import * as FileSystem from "expo-file-system/legacy";
import { File, Paths } from "expo-file-system";
 
export async function readLegacyManifest() {
  const file = new File(Paths.cache, "legacy-manifest.json");
  if (!file.exists) return null;
  const text = await FileSystem.readAsStringAsync(file.uri);
  return JSON.parse(text) as { version: number };
}

O que isso demonstra:

Paths.document para PDFs significativos para o usuário - sobrevive a varreduras de cache.
createDownloadTask com callback de progresso para barras de UI.
Directory.list() para enumerar pastas de trabalhos.
Importação legada para caminhos de leitura não migrados - planeje a remoção por versão.

Mergulho Profundo

Diretórios com Sandbox

Caminho	Persistência	Uso Típico
`Paths.document`	Até a desinstalação do aplicativo	Exportações do usuário, PDFs de inspeção
`Paths.cache`	O SO pode remover	Miniaturas, downloads temporários
`Paths.bundle`	Ativos empacotados somente leitura	Arquivos iniciais no primeiro lançamento

import { Paths } from "expo-file-system";
 
console.log(Paths.document.uri);
console.log(Paths.cache.uri);

Nunca assuma que os arquivos de cache existem após eventos de baixo armazenamento - baixe novamente ou verifique file.exists.
document é incluído em backups de dispositivos no iOS, a menos que excluído - não coloque segredos aqui.

API Moderna de Arquivos e Diretórios

const dir = new Directory(Paths.cache, "avatars");
dir.create({ intermediates: true });
 
const avatar = dir.createFile("user-42.jpg", "image/jpeg");
avatar.write(bytes);
 
const copy = new File(Paths.cache, "avatars", "user-42-copy.jpg");
avatar.copy(copy);
 
avatar.move(new Directory(Paths.document, "archive"));

Construtores aceitam segmentos de caminho - evitam bugs de concatenação manual de strings file://.
Propriedade exists antes da leitura - erros são para tipo de Arquivo/Diretório incorreto em caminhos existentes.
textSync / bytesSync para arquivos pequenos - variantes assíncronas para cargas úteis grandes.

Downloads e Uploads

// Download simples de uma vez
await File.downloadFileAsync(url, new Directory(Paths.cache, "pdfs"));
 
// Upload com progresso
const file = new File(Paths.document, "photo.jpg");
const task = file.createUploadTask("https://api.example.com/upload", {
  uploadType: File.UploadType?.MULTIPART ?? 1,
  onProgress: ({ bytesSent, totalBytes }) => {
    console.log(bytesSent, totalBytes);
  },
});
await task.uploadAsync();

Prefira expo/fetch com corpo File para multipart quando as opções de tarefa de upload forem excessivas.
Veja ../networking-api/fetch-vs-axios/fetch-vs-axios.md para restrições de upload do RN.

Migração Legada

// Antes (legado)
import * as FileSystem from "expo-file-system/legacy";
await FileSystem.readAsStringAsync(uri);
 
// Depois (SDK 57)
import { File } from "expo-file-system";
const file = new File(uri);
const text = file.textSync();

Importe expo-file-system/legacy apenas em locais de chamada não migrados.
Período de ponte: crie File a partir de strings de URI legadas - new File(existingUri).
Remova importações legadas quando npx expo doctor e grep não mostrarem mais importações /legacy.

Plugin de Configuração (Opcional)

{
  "expo": {
    "plugins": [
      [
        "expo-file-system",
        {
          "enableFileSharing": true,
          "supportsOpeningDocumentsInPlace": true
        }
      ]
    ]
  }
}

Habilita a visibilidade do aplicativo Arquivos do iOS para documentDirectory - útil para PDFs exportados.

Armadilhas

Armazenar tokens em arquivos de cache JSON - Legível em dispositivos comprometidos. Correção: expo-secure-store.
Assumir que caminhos de cache sobrevivem à reinicialização - O SO remove o cache. Correção: Persista arquivos críticos em Paths.document.
Concatenar URIs manualmente - Barras duplas quebram o Android. Correção: new File(Paths.cache, "a", "b.txt").
Colunas BLOB no SQLite para fotos - Inchaço do banco de dados. Correção: Arquivo no disco + coluna de caminho.
Leitura síncrona de arquivos de vários MB na thread da UI - Travamentos. Correção: bytes() / streams assíncronos.
Omitir intermediates: true - create() aninhado falha. Correção: { intermediates: true } em caminhos profundos.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
API `File` / `Directory`	Novo código SDK 57	Manutenção de aplicativos SDK 54 sem largura de banda de migração
`expo-file-system/legacy`	Módulos não migrados	Recursos Greenfield
`expo-sqlite`	Linhas relacionais	Grandes blobs binários
`AsyncStorage`	Preferências JSON pequenas	Arquivos maiores que alguns KB

FAQs

Como instalo o expo-file-system no SDK 57?

npx expo install expo-file-system

Importe { File, Directory, Paths } de expo-file-system - não apenas o namespace padrão.

Quando devo usar cache vs document?

cache - downloads reproduzíveis, miniaturas, processamento temporário.
document - exportações criadas pelo usuário que o aplicativo não deve excluir silenciosamente.

Como verifico o espaço livre?

O Expo não expõe a cota de disco - lide com falhas de gravação graciosamente e apresente a UX de "armazenamento cheio".
Limpe os diretórios Paths.cache na atualização da versão do aplicativo ou em uma ação de configurações.

Posso ler ativos empacotados?

import { File, Paths } from "expo-file-system";
const seed = new File(Paths.bundle, "seed-data.json");

Caminhos de bundle são somente leitura - copie para cache/documento antes da mutação.

Como excluo uma pasta de trabalho?

const dir = new Directory(Paths.document, "inspections", jobId);
if (dir.exists) dir.delete(); // recursivo

Relacionados

Noções Básicas do Expo SDK - APIs legadas vs modernas
expo-camera & expo-image-picker - URIs de captura
expo-secure-store & expo-crypto - segredos, não arquivos
../data-offline/expo-sqlite/expo-sqlite.md - caminhos em linhas de DB
../networking-api/fetch-vs-axios/fetch-vs-axios.md - progresso de upload
Melhores Práticas de Pacotes do Expo SDK - regras de níveis de armazenamento

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

npx expo install expo-file-system

import { Directory, File, Paths } from "expo-file-system";
 
export function ensureDownloadDir() {
  const dir = new Directory(Paths.cache, "downloads");
  if (!dir.exists) {
    dir.create();
  }
  return dir;
}
 
export async function downloadPdf(url: string, filename: string) {
  const dir = ensureDownloadDir();
  const output = await File.downloadFileAsync(url, dir);
  return output.uri;
}
 
export function writeJsonCache(name: string, data: unknown) {
  const file = new File(Paths.cache, `${name}.json`);
  if (!file.exists) {
    file.create();
  }
  file.write(JSON.stringify(data));
}

Quando usar isso:

Cache de respostas de API ou PDFs para leitura offline.
Persistência de fotos geradas pelo usuário antes do upload em segundo plano.
Leitura de ativos empacotados copiados para o cache gravável.
Upload de arquivos com progresso File.createUploadTask.

Quando evitar:

Segredos e tokens - use expo-secure-store.
Dados relacionais estruturados - use SQLite; armazene apenas caminhos.
Reprodução de mídia de streaming de grande porte - considere caches de mídia dedicados/CDN.

Exemplo de Trabalho

Download com progresso, metadados JSON auxiliares e interoperabilidade legada durante a migração.

npx expo install expo-file-system

// src/files/downloadWithProgress.ts
import { Directory, File, Paths } from "expo-file-system";
 
export async function downloadInspectionPdf(
  url: string,
  jobId: string,
  onProgress: (ratio: number) => void
) {
  const dir = new Directory(Paths.document, "inspections", jobId);
  if (!dir.exists) {
    dir.create({ intermediates: true });
  }
 
  const destination = new File(dir, "report.pdf");
  const task = File.createDownloadTask(url, destination, {
    onProgress: ({ bytesWritten, totalBytes }) => {
      if (totalBytes > 0) {
        onProgress(bytesWritten / totalBytes);
      }
    },
  });
 
  const file = await task.downloadAsync();
  if (!file) throw new Error("Download paused or cancelled");
 
  const meta = new File(dir, "meta.json");
  meta.create();
  meta.write(JSON.stringify({ url, downloadedAt: Date.now() }));
 
  return file.uri;
}

// src/files/listInspections.ts
import { Directory, Paths } from "expo-file-system";
 
export function listInspectionJobIds(): string[] {
  const root = new Directory(Paths.document, "inspections");
  if (!root.exists) return [];
 
  return root
    .list()
    .filter((entry) => entry instanceof Directory)
    .map((d) => d.name);
}

// src/files/legacyRead.ts - ponte temporária
import * as FileSystem from "expo-file-system/legacy";
import { File, Paths } from "expo-file-system";
 
export async function readLegacyManifest() {
  const file = new File(Paths.cache, "legacy-manifest.json");
  if (!file.exists) return null;
  const text = await FileSystem.readAsStringAsync(file.uri);
  return JSON.parse(text) as { version: number };
}

O que isso demonstra:

Paths.document para PDFs significativos para o usuário - sobrevive a varreduras de cache.
createDownloadTask com callback de progresso para barras de UI.
Directory.list() para enumerar pastas de trabalhos.
Importação legada para caminhos de leitura não migrados - planeje a remoção por versão.

Mergulho Profundo

Diretórios com Sandbox

Caminho	Persistência	Uso Típico
`Paths.document`	Até a desinstalação do aplicativo	Exportações do usuário, PDFs de inspeção
`Paths.cache`	O SO pode remover	Miniaturas, downloads temporários
`Paths.bundle`	Ativos empacotados somente leitura	Arquivos iniciais no primeiro lançamento

import { Paths } from "expo-file-system";
 
console.log(Paths.document.uri);
console.log(Paths.cache.uri);

Nunca assuma que os arquivos de cache existem após eventos de baixo armazenamento - baixe novamente ou verifique file.exists.
document é incluído em backups de dispositivos no iOS, a menos que excluído - não coloque segredos aqui.

API Moderna de Arquivos e Diretórios

const dir = new Directory(Paths.cache, "avatars");
dir.create({ intermediates: true });
 
const avatar = dir.createFile("user-42.jpg", "image/jpeg");
avatar.write(bytes);
 
const copy = new File(Paths.cache, "avatars", "user-42-copy.jpg");
avatar.copy(copy);
 
avatar.move(new Directory(Paths.document, "archive"));

Construtores aceitam segmentos de caminho - evitam bugs de concatenação manual de strings file://.
Propriedade exists antes da leitura - erros são para tipo de Arquivo/Diretório incorreto em caminhos existentes.
textSync / bytesSync para arquivos pequenos - variantes assíncronas para cargas úteis grandes.

Downloads e Uploads

// Download simples de uma vez
await File.downloadFileAsync(url, new Directory(Paths.cache, "pdfs"));
 
// Upload com progresso
const file = new File(Paths.document, "photo.jpg");
const task = file.createUploadTask("https://api.example.com/upload", {
  uploadType: File.UploadType?.MULTIPART ?? 1,
  onProgress: ({ bytesSent, totalBytes }) => {
    console.log(bytesSent, totalBytes);
  },
});
await task.uploadAsync();

Prefira expo/fetch com corpo File para multipart quando as opções de tarefa de upload forem excessivas.
Veja ../networking-api/fetch-vs-axios/fetch-vs-axios.md para restrições de upload do RN.

Migração Legada

// Antes (legado)
import * as FileSystem from "expo-file-system/legacy";
await FileSystem.readAsStringAsync(uri);
 
// Depois (SDK 57)
import { File } from "expo-file-system";
const file = new File(uri);
const text = file.textSync();

Importe expo-file-system/legacy apenas em locais de chamada não migrados.
Período de ponte: crie File a partir de strings de URI legadas - new File(existingUri).
Remova importações legadas quando npx expo doctor e grep não mostrarem mais importações /legacy.

Plugin de Configuração (Opcional)

{
  "expo": {
    "plugins": [
      [
        "expo-file-system",
        {
          "enableFileSharing": true,
          "supportsOpeningDocumentsInPlace": true
        }
      ]
    ]
  }
}

Habilita a visibilidade do aplicativo Arquivos do iOS para documentDirectory - útil para PDFs exportados.

Armadilhas

Armazenar tokens em arquivos de cache JSON - Legível em dispositivos comprometidos. Correção: expo-secure-store.
Assumir que caminhos de cache sobrevivem à reinicialização - O SO remove o cache. Correção: Persista arquivos críticos em Paths.document.
Concatenar URIs manualmente - Barras duplas quebram o Android. Correção: new File(Paths.cache, "a", "b.txt").
Colunas BLOB no SQLite para fotos - Inchaço do banco de dados. Correção: Arquivo no disco + coluna de caminho.
Leitura síncrona de arquivos de vários MB na thread da UI - Travamentos. Correção: bytes() / streams assíncronos.
Omitir intermediates: true - create() aninhado falha. Correção: { intermediates: true } em caminhos profundos.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
API `File` / `Directory`	Novo código SDK 57	Manutenção de aplicativos SDK 54 sem largura de banda de migração
`expo-file-system/legacy`	Módulos não migrados	Recursos Greenfield
`expo-sqlite`	Linhas relacionais	Grandes blobs binários
`AsyncStorage`	Preferências JSON pequenas	Arquivos maiores que alguns KB

FAQs

Como instalo o expo-file-system no SDK 57?

npx expo install expo-file-system

Importe { File, Directory, Paths } de expo-file-system - não apenas o namespace padrão.

Quando devo usar cache vs document?

cache - downloads reproduzíveis, miniaturas, processamento temporário.
document - exportações criadas pelo usuário que o aplicativo não deve excluir silenciosamente.

Como verifico o espaço livre?

O Expo não expõe a cota de disco - lide com falhas de gravação graciosamente e apresente a UX de "armazenamento cheio".
Limpe os diretórios Paths.cache na atualização da versão do aplicativo ou em uma ação de configurações.

Posso ler ativos empacotados?

import { File, Paths } from "expo-file-system";
const seed = new File(Paths.bundle, "seed-data.json");

Caminhos de bundle são somente leitura - copie para cache/documento antes da mutação.

Como excluo uma pasta de trabalho?

const dir = new Directory(Paths.document, "inspections", jobId);
if (dir.exists) dir.delete(); // recursivo

Relacionados

Noções Básicas do Expo SDK - APIs legadas vs modernas
expo-camera & expo-image-picker - URIs de captura
expo-secure-store & expo-crypto - segredos, não arquivos
../data-offline/expo-sqlite/expo-sqlite.md - caminhos em linhas de DB
../networking-api/fetch-vs-axios/fetch-vs-axios.md - progresso de upload
Melhores Práticas de Pacotes do Expo SDK - regras de níveis de armazenamento

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

expo-file-system

Buscar na documentação

expo-file-system