> ## 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: upload e commit de arquivos

> Crie aplicações a partir de um zip com apps.create() e envie arquivos para uma aplicação existente com apps.commit(), a partir de um caminho, um Blob ou bytes.

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.

## Entradas aceitas

`apps.create()` e `apps.commit()` aceitam:

| Entrada | Onde | Observações |
| - | - | - |
| Um caminho de arquivo (`string`) | Node.js, Deno, Bun | Aberto com `fs.openAsBlob` e transmitido do disco, nunca lido para a memória |
| `Blob` / `File` | Em todo lugar | O nome de um `File` é usado como nome do arquivo |
| `Uint8Array` (ou `Buffer`) | Em todo lugar | |

Em edge runtimes e no navegador, passe um `Blob`, `File` ou `Uint8Array`: um caminho só funciona onde `node:fs` existe.

Os uploads são **limitados a 100 MB**. Um arquivo maior falha localmente com `FILE_TOO_LARGE` (status `0`) antes que qualquer coisa seja enviada. Os uploads são transmitidos em stream e **não têm timeout**: passe um `signal` para cancelar um.

## Criando uma aplicação

`apps.create(file)` faz o deploy de um `.zip` que contém um arquivo de configuração [`squarecloud.app`](/pt-br/getting-started/config-file) na raiz.

```typescript theme={"system"}
const app = await api.apps.create("./bot.zip");

console.log(app.id, app.name, app.ram, app.cpu, app.language.name, app.language.version);
console.log(app.domain);  // "<subdomain>.squareweb.app" for web apps, absent otherwise
console.log(app.cluster); // the cluster the app was placed on
```

| Campo | Descrição |
| - | - |
| `id` | O id da nova aplicação |
| `name` | Nome vindo do arquivo de configuração |
| `description` | Presente apenas quando definido |
| `domain` | Host completo `<subdomain>.squareweb.app`; ausente para aplicações que não são web |
| `cluster` | Cluster em que a aplicação foi alocada |
| `ram` / `cpu` | Recursos alocados |
| `language` | `{ name, version }` |

## Fazendo commit em uma aplicação

`apps.commit(appId, file, { path, filename, signal })` envia um arquivo para uma aplicação existente:

* Um `.zip` é **descompactado** em `path` (a raiz da aplicação por padrão).
* Qualquer outro arquivo vai para `path/<filename>`.

O nome do arquivo é `filename`, senão o próprio nome do arquivo (caminho ou `File`), senão `commit.zip`.

```typescript theme={"system"}
// Unpack a zip at the root
await api.apps.commit(appId, "./build.zip");

// Unpack a zip into /src
await api.apps.commit(appId, "./patch.zip", { path: "/src" });

// A single file from memory: /src/index.js
await api.apps.commit(appId, new Blob([code]), { path: "/src", filename: "index.js" });
```

Um commit não reinicia a aplicação. Chame [`apps.restart()`](/pt-br/sdks/js/managing_application#iniciar-parar-e-reiniciar) para aplicá-lo.

## Cancelando um upload

```typescript theme={"system"}
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 120_000);

try {
    await api.apps.create("./bot.zip", { signal: controller.signal });
} finally {
    clearTimeout(timer);
}
```

Um upload abortado rejeita com o `reason` do signal.

## Erros

| Status | Código | Quando |
| - | - | - |
| 0 | `FILE_TOO_LARGE` | O arquivo tem mais de 100 MB (verificado localmente) |
| 400 | `INVALID_FILE`, `INVALID_FILENAME` | Nenhum arquivo, ou um nome de arquivo com separadores de caminho, `..` ou caracteres de controle |
| 400 | `INVALID_PATH` | `path` contém travessia de diretório ou metacaracteres de shell (commit) |
| 400 | `INSUFFICIENT_MEMORY` | Menos de 256 MB de memória disponível no plano (create) |
| 400 | `COMMIT_FAILED` | O commit não pôde ser aplicado (commit) |
| 400 | `UPLOAD_FAILED`, `STORAGE_UPLOAD_FAILED`, `CLUSTER_SELECTION_FAILED` | O upload não pôde ser processado (create) |
| 503 | `CLUSTER_MAINTENANCE_TRY_LATER` | O provisionamento está pausado para manutenção (create) |
| 503 | `UPLOAD_BUSY` | Uploads demais em andamento: tentado novamente de forma automática |

Um caminho local que não pode ser aberto lança o erro do sistema de arquivos, não um `SquareCloudAPIError`. Veja [Erros](/pt-br/sdks/js/errors) para a lista completa.

## Próximos passos

<CardGroup cols={3}>
  <Card title="Gerenciando arquivos" icon="folder-open" href="/pt-br/sdks/js/managing_files">
    Liste, leia, escreva, mova e exclua arquivos da aplicação.
  </Card>

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

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


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