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

# ambarks.json

> Configure comandos de instalação, build e start do seu projeto.

# <Icon icon="golf-flag-hole" color="#0516ee" size={30} /> Como usar `ambarks.json`

O arquivo `ambarks.json` permite dizer ao AmbarksCloud como preparar e iniciar seu projeto quando o comportamento automático não é suficiente.

Crie o arquivo na raiz do projeto:

```text theme={null}
meu-projeto/
  ambarks.json
  package.json
  src/
```

Também é aceito o nome `ambarks.config.json`.

## Exemplo completo

```json theme={null}
{
  "build": {
    "installCommand": "npm ci",
    "buildCommand": "npm run build"
  },
  "run": {
    "command": "npm run start"
  }
}
```

## Campos (resumo)

| Campo                  | Obrigatório | Uso                                           |
| ---------------------- | ----------- | --------------------------------------------- |
| `build.installCommand` | não         | Comando para instalar dependências            |
| `build.install`        | não         | Atalho alternativo para comando de instalação |
| `build.buildCommand`   | não         | Comando para gerar build                      |
| `build.command`        | não         | Atalho alternativo para comando de build      |
| `run.command`          | sim         | Comando usado para iniciar a aplicação        |

## Regras importantes

* O JSON precisa ser válido.
* O arquivo deve estar na raiz do projeto enviado.
* O comando de start deve manter o processo rodando.
* Servidores web devem escutar em `0.0.0.0`.
* A porta usada pelo comando deve bater com a porta interna configurada no projeto.

## Exemplos por stack

### Discord bot (Node.js)

Para bots, o mais importante é: processo em execução e logs claros (não há porta HTTP).

```json theme={null}
{
  "build": {
    "installCommand": "npm ci"
  },
  "run": {
    "command": "node src/bot.js"
  }
}
```

Veja: [Deploy de bot Discord (Node.js)](/guias/discord-bot-node).

### Express (Node.js)

```json theme={null}
{
  "build": {
    "installCommand": "npm ci"
  },
  "run": {
    "command": "node server.js"
  }
}
```

### FastAPI (Python)

```json theme={null}
{
  "build": {
    "installCommand": "pip install --no-cache-dir -r requirements.txt"
  },
  "run": {
    "command": "uvicorn main:app --host 0.0.0.0 --port 8000"
  }
}
```

### Site estático com build (Vite)

```json theme={null}
{
  "build": {
    "installCommand": "npm ci",
    "buildCommand": "npm run build"
  },
  "run": {
    "command": "npm run preview -- --host 0.0.0.0 --port 4173"
  }
}
```

## Exemplos inválidos (e por quê)

### JSON inválido

```json theme={null}
{ "run": { "command": "npm start", } }
```

Motivo: vírgula extra.

### Campo desconhecido

```json theme={null}
{
  "run": { "command": "npm start" },
  "startCommand": "npm start"
}
```

Motivo: `startCommand` não é um campo reconhecido.

### `run.command` vazio

```json theme={null}
{ "run": { "command": "" } }
```

Motivo: o comando precisa ser uma string não vazia.

## Quando não usar

Se seu projeto precisa instalar pacotes do sistema, copiar arquivos para pastas específicas ou usar várias etapas de build, prefira Dockerfile.

## Links relacionados

* [Guias por stack](/guias/visao-geral)
* [Dockerfile personalizado](/projetos/dockerfile)
* [Portas e domínios](/projetos/portas-dominios)