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

# SDK JavaScript: gerenciador de arquivos da aplicação

> Liste, leia, escreva, mova e exclua os arquivos de uma aplicação com api.apps.files. O conteúdo trafega em base64, então binários chegam intactos.

O gerenciador de arquivos fica em `api.apps.files`. Todo método recebe o id da aplicação primeiro e, em seguida, um caminho dentro da aplicação. Os caminhos têm no máximo **256 caracteres**.

Os exemplos usam o cliente `api` de [Criando o cliente](/pt-br/sdks/js/client#criando-o-cliente). `appId` é o id de uma das suas aplicações: [`api.account.me()`](/pt-br/sdks/js/client#conta) lista todas.

## Listando um diretório

`files.list(appId, path?)` lista um diretório (a raiz da aplicação quando `path` é omitido).

```typescript theme={"system"}
for (const entry of await api.apps.files.list(appId, "/src")) {
    console.log(entry.type, entry.name, entry.size, entry.lastModified);
}
```

| Campo | Tipo | Descrição |
| - | - | - |
| `name` | `string` | Nome da entrada |
| `type` | `"file" \| "directory"` | Tipo da entrada |
| `size` | `number?` | Tamanho em bytes. Ausente em algumas entradas de diretório |
| `lastModified` | `number \| null?` | Unix ms (pode ter fração); `null` quando ilegível |

Um diretório que não existe resulta em 404 `FILE_NOT_FOUND`. Um caminho que o gerenciador de arquivos não expõe resulta em 403 `BLOCKED_PATH`.

## Lendo um arquivo

`files.read(appId, path)` retorna os bytes do arquivo como um `Uint8Array`. Os arquivos são limitados a **10 MB**: um maior resulta em 413 `FILE_TOO_LARGE`.

```typescript theme={"system"}
const bytes = await api.apps.files.read(appId, "/config.json");
const text = new TextDecoder().decode(bytes);

console.log(JSON.parse(text));
```

## Escrevendo um arquivo

`files.write(appId, path, content, { signal })` cria ou sobrescreve um arquivo.

* Uma `string` é enviada como texto simples.
* Um `Uint8Array` é enviado como base64, então qualquer conteúdo binário chega intacto.
* Conteúdo vazio (`""` ou bytes vazios) cria um arquivo vazio.

```typescript theme={"system"}
// Text
await api.apps.files.write(appId, "/config.json", JSON.stringify({ debug: false }));

// Binary
const image = new Uint8Array(await (await fetch(imageUrl)).arrayBuffer());
await api.apps.files.write(appId, "/assets/logo.png", image);
```

Conteúdo acima de **10 MB** falha localmente com `FILE_TOO_LARGE` (status `0`) antes que qualquer coisa seja enviada. Conteúdo acima de **1 MiB** é enviado sem timeout, como um upload: passe `{ signal }` para cancelá-lo. Para arquivos maiores, use [`apps.commit()`](/pt-br/sdks/js/commit_and_upload).

<Note>
  Escrever não reinicia a aplicação. Chame [`apps.restart()`](/pt-br/sdks/js/managing_application#iniciar-parar-e-reiniciar) para aplicar a alteração.
</Note>

## Movendo ou renomeando um arquivo

```typescript theme={"system"}
await api.apps.files.move(appId, "/config.json", "/config.old.json");
```

## Excluindo um arquivo

```typescript theme={"system"}
await api.apps.files.delete(appId, "/config.old.json");
```

## Erros

| Status | Código | Quando |
| - | - | - |
| 0 | `FILE_TOO_LARGE` | Conteúdo de `write` acima de 10 MB (verificado localmente) |
| 400 | `INVALID_PATH` | O caminho falha na validação (travessia de diretório, caracteres inválidos, longo demais), ou `move` para o mesmo caminho |
| 400 | `DELETE_FAILED`, `RENAME_FAILED` | O cluster não conseguiu excluir ou renomear o arquivo |
| 403 | `BLOCKED_PATH` | O caminho não é exposto pelo gerenciador de arquivos |
| 403 | `PERMISSION_DENIED` | Seu cargo no workspace não pode mexer em um arquivo restrito (como `.env`) |
| 404 | `FILE_NOT_FOUND` | O arquivo ou diretório não existe |
| 413 | `FILE_TOO_LARGE` | `read` de um arquivo acima de 10 MB |
| 429 | `KEEP_CALM` | Mais de 10 escritas em 5 segundos |

Veja [Erros](/pt-br/sdks/js/errors) para os códigos que qualquer chamada pode retornar.

## Próximos passos

<CardGroup cols={3}>
  <Card title="Variáveis de ambiente" icon="key" href="/pt-br/sdks/js/environment_variables">
    Leia e altere as variáveis de uma aplicação.
  </Card>

  <Card title="Referência da API do gerenciador de arquivos" icon="code" href="/pt-br/api-reference/endpoint/apps/filemanager/list">
    Os endpoints REST por trás destes métodos.
  </Card>

  <Card title="Arquivos pela CLI" icon="terminal" href="/pt-br/cli-reference/files">
    As mesmas ações pelo terminal.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.