> ## 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.

# Hospede uma aplicação, API ou bot em Node.js

> Faça deploy de aplicações, APIs e bots de Discord em Node.js e TypeScript: defina MAIN e START, instale dependências do package.json e fique no ar em minutos.

O runtime Node.js roda bots, APIs e sites renderizados no servidor em JavaScript e TypeScript. A Square Cloud instala as suas dependências a partir do `package.json` e inicia a sua aplicação com o Node.js.

## Antes de começar

* Node.js e npm na sua máquina. Se ainda não os tiver, baixe-os no [site oficial do Node.js](https://nodejs.org/).
* Uma conta na Square Cloud: [cadastre-se](https://squarecloud.app/pt-br/signup) com seu e-mail ou GitHub.
* Um plano ativo. Veja os [planos](https://squarecloud.app/pt-br/pricing) e escolha o que combina com o seu projeto.

## Configure a Square Cloud

<Note>
  Se você envia sua aplicação pelo dashboard, pode pular esta seção: o dashboard cria o arquivo de configuração `squarecloud.app` para você.
</Note>

<Card title="Referência do arquivo de configuração" icon="link" href="/pt-br/getting-started/config-file">
  O arquivo `squarecloud.app` diz à Square Cloud como executar a sua aplicação: o arquivo principal, a memória, a versão do runtime, o nome e, para um site, o subdomínio.
</Card>

Um arquivo de configuração completo para cada tipo de aplicação:

<Tabs>
  <Tab title="Bot ou worker">
    ```systemd squarecloud.app theme={"system"}
    MAIN=index.js
    MEMORY=256
    VERSION=recommended
    DISPLAY_NAME=My bot
    ```
  </Tab>

  <Tab title="Site ou API">
    ```systemd squarecloud.app theme={"system"}
    MAIN=index.js
    MEMORY=512
    VERSION=recommended
    DISPLAY_NAME=My website
    SUBDOMAIN=mywebsite
    ```
  </Tab>
</Tabs>

`VERSION=recommended` roda a linha LTS atual do Node.js, e `VERSION=latest` a versão mais recente.

## O que a Square Cloud executa

<Tabs>
  <Tab title="JavaScript">
    * Se o campo `START` não estiver definido no arquivo de configuração, a Square Cloud executa `node MAIN`. Quando a aplicação tem 1024 MB de memória ou mais, ela adiciona `--max_old_space_size=<MEMORY>` (o limite do heap do Node.js, em MB). Se o campo `START` estiver definido, o valor nele será executado diretamente. Para mais informações sobre os parâmetros do arquivo de configuração, visite [parâmetros de configuração](/pt-br/getting-started/config-file#parâmetros-de-configuração).
  </Tab>

  <Tab title="TypeScript">
    * Se o campo `START` não estiver definido no arquivo de configuração, a Square Cloud executa `npx tsx MAIN`, que executa diretamente o arquivo TypeScript especificado em `MAIN`. O `tsx` é instalado junto com as suas dependências. Se o campo `START` estiver definido, o valor nele será executado diretamente. Para mais informações sobre os parâmetros do arquivo de configuração, visite [parâmetros de configuração](/pt-br/getting-started/config-file#parâmetros-de-configuração).
  </Tab>
</Tabs>

* Se a aplicação não tiver uma pasta `node_modules`, a Square Cloud executa `npm install --no-audit --no-fund` antes de iniciá-la. Os pacotes em `devDependencies` não são instalados, porque o runtime define `NODE_ENV=production`. Quando a `node_modules` já existe, a etapa de instalação é pulada.

### Porta e host para sites e APIs

A Square Cloud define a variável de ambiente `PORT` como `80` e `HOST` como `0.0.0.0`. O seu servidor precisa escutar nessa porta e em todas as interfaces de rede, por exemplo com o Express:

```javascript theme={"system"}
const port = Number(process.env.PORT) || 80;
app.listen(port, '0.0.0.0');
```

Next.js, Nuxt, React Router, Astro e SolidStart leem a `PORT` sozinhos: os [guias de frameworks](#guias-de-frameworks) dizem quando não há nada para mudar.

## Prepare o projeto

### Arquivos necessários

* [`squarecloud.app`](/pt-br/getting-started/config-file), na raiz do ZIP.
* O seu arquivo principal, por exemplo `index.js` ou `src/index.ts`.
* [`package.json`](/pt-br/articles/how-to-create-your-package-json), com as suas dependências. Um upload sem ele falha com `INVALID_DEPENDENCY`.

<Warning>O arquivo de configuração (`squarecloud.app`) deve estar localizado na raiz do arquivo zip. Caso contrário, a Square Cloud não conseguirá encontrá-lo durante o deploy.</Warning>

<Note>
  A Square Cloud roda TypeScript nativamente com o `tsx` (`npx tsx MAIN`), mas compilar para JavaScript continua sendo o recomendado em produção: faça o build na sua máquina e aponte o `MAIN` para o arquivo compilado.
</Note>

### O que deixar de fora

* `node_modules`: a Square Cloud remove esta pasta do seu upload e instala as dependências do `package.json` na primeira inicialização. Isso deixa o upload pequeno e compila as dependências para o sistema do servidor.
* Lockfiles (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`): a CLI e a extensão do VS Code deixam esses arquivos de fora por padrão, então o npm instala as versões mais recentes permitidas pelos intervalos do `package.json`. Quando você precisar das versões exatas do seu lockfile, inclua-o de volta com `!package-lock.json` no seu [`squarecloud.ignore`](/pt-br/getting-started/squarecloud-ignore).

## Guias de frameworks

<CardGroup cols={3}>
  <Card title="Express" icon="network-wired" href="/pt-br/tutorials/api/express" />

  <Card title="Fastify" icon="cat" href="/pt-br/tutorials/api/fastify" />

  <Card title="NestJS" icon="wifi" href="/pt-br/tutorials/api/nestjs" />

  <Card title="Next.js" icon="n" href="/pt-br/tutorials/website/nextjs" />

  <Card title="Nuxt" icon="mountains" href="/pt-br/tutorials/website/nuxt" />

  <Card title="React Router" icon="bolt" href="/pt-br/tutorials/website/remix" />

  <Card title="Angular" icon="angular" href="/pt-br/tutorials/website/angular" />

  <Card title="Astro" icon="rocket-vertical" href="/pt-br/tutorials/website/astrojs" />

  <Card title="SolidJS" icon="s" href="/pt-br/tutorials/website/solidjs" />

  <Card title="Qwik" icon="circle-bolt" href="/pt-br/tutorials/website/qwik" />

  <Card title="React" icon="react" href="/pt-br/tutorials/website/react" />

  <Card title="Vue" icon="vuejs" href="/pt-br/tutorials/website/vue" />
</CardGroup>

Aplicações single-page feitas com Vite, React, Vue ou Preact também podem rodar sem Node.js, no [runtime estático](/pt-br/articles/getting-started-with-html).

## Solução de problemas

<AccordionGroup>
  <Accordion title="O arquivo principal é inválido ou está corrompido" icon="file" iconType="solid">
    Este erro ocorre quando o arquivo definido como "main" para sua aplicação no
    arquivo de configuração não existe, está escrito incorretamente ou o caminho
    está errado. Se o seu arquivo principal estiver dentro de uma pasta, por
    exemplo, você deve informar `pasta/arquivo.js`.
  </Accordion>

  <Accordion title="Memória insuficiente" icon="memory" iconType="solid">
    A quantidade mínima de RAM necessária para hospedar um bot é 256MB e para
    um site/API é 512MB. No entanto, dependendo do tamanho e complexidade da
    sua aplicação, pode ser aconselhável alocar uma quantidade maior de RAM para
    evitar que a aplicação fique sem memória e trave.
  </Accordion>
</AccordionGroup>

Para outros problemas, veja [Solução de problemas](/pt-br/platform/troubleshooting).

## Faça o deploy

### Via dashboard

<Steps>
  <Step title="Acesse a página de upload">
    Acesse a [página de upload](https://squarecloud.app/pt-br/dashboard/new) e envie seu arquivo zip.
  </Step>

  <Step title="Configure seu ambiente">
    Após fazer o upload do seu arquivo zip, você precisará configurar o nome, o arquivo principal ou o ambiente de execução e outras configurações do seu projeto.\
    Se você estiver enviando um projeto web, certifique-se de selecionar "Publicação na Web" e definir um subdomínio para o seu projeto.
  </Step>

  <Step title="Faça o deploy do projeto">
    Por fim, clique no botão "Deploy" para hospedar seu projeto na Square Cloud.
    Após o deploy, você poderá monitorar o status e os registros do seu projeto no dashboard.

    <Frame>
      <img src="https://cdn.squarecloud.app/docs/articles/dashboard/uploading-pt-br.gif" alt="Enviando aplicação para a Square Cloud" style={{ borderRadius: "0.2rem" }} />
    </Frame>
  </Step>

  <Step title="Confirme que seu app está no ar">
    Seu primeiro deploy geralmente leva menos de um minuto. No [dashboard](https://squarecloud.app/pt-br/dashboard), aguarde o status da sua aplicação mudar para em execução e verifique os registros em busca de erros de inicialização.\
    Se você fez deploy de um site ou API, abra `https://<seu-subdominio>.squareweb.app` no navegador: você deve ver sua aplicação respondendo. Se você fez deploy de um bot, envie um comando para confirmar que ele está online.
    <Tip>Seu app não está iniciando? Veja o [guia de solução de problemas](/pt-br/platform/troubleshooting/app-wont-start) para as causas e correções mais comuns.</Tip>
  </Step>
</Steps>

### Via CLI

Para usar esse método, seu projeto precisa de um arquivo de configuração chamado `squarecloud.app` na raiz. Ele informa à Square Cloud como executar a sua aplicação.

<Card title="Guia do arquivo de configuração" icon="link" href="/pt-br/getting-started/config-file">
  Saiba como criar o arquivo de configuração `squarecloud.app` que define o ambiente da sua aplicação.
</Card>

<Steps>
  <Step title="Instale a CLI">
    Instale a [CLI da Square Cloud](/pt-br/cli-reference/installation). Se você já a tem, execute o mesmo comando para atualizá-la:

    <CodeGroup>
      ```bash macOS, Linux e WSL theme={"system"}
      curl -fsSL https://cli.squarecloud.app/install | bash
      ```

      ```bash Windows com npm theme={"system"}
      npm install -g @squarecloud/cli@latest
      ```
    </CodeGroup>
  </Step>

  <Step title="Faça login">
    Execute o comando abaixo. Ele abre o seu navegador: aprove o login lá e a CLI está pronta. Não há nenhuma chave de API para copiar. Para scripts e CI, veja [autenticação da CLI](/pt-br/cli-reference/authentication).

    ```bash theme={"system"}
    squarecloud auth login
    ```
  </Step>

  <Step title="Envie o seu projeto">
    Na pasta do seu projeto, execute o comando abaixo. A CLI compacta a pasta atual, deixando de fora o que o [`squarecloud.ignore`](/pt-br/getting-started/squarecloud-ignore) lista, e faz o upload:

    ```bash theme={"system"}
    squarecloud upload
    ```

    Para enviar um zip que você mesmo criou, passe-o com `--file`:

    ```bash theme={"system"}
    squarecloud upload --file <caminho/para/zip>
    ```
  </Step>

  <Step title="Confirme que seu app está no ar">
    Seu primeiro deploy geralmente leva menos de um minuto. Verifique o status e os registros da sua aplicação diretamente pelo terminal:

    ```bash theme={"system"}
    squarecloud app status
    squarecloud app logs
    ```

    Se você fez deploy de um site ou API, abra `https://<seu-subdominio>.squareweb.app` no navegador: você deve ver sua aplicação respondendo. Se você fez deploy de um bot, envie um comando para confirmar que ele está online.
    <Tip>Seu app não está iniciando? Veja o [guia de solução de problemas](/pt-br/platform/troubleshooting/app-wont-start) para as causas e correções mais comuns.</Tip>
  </Step>
</Steps>

## Próximos passos

<CardGroup cols={3}>
  <Card title="Variáveis de ambiente" icon="key" href="/pt-br/platform/environment-variables">
    Mantenha segredos e configurações fora do código e leia-os em tempo de execução.
  </Card>

  <Card title="Domínio personalizado" icon="globe" href="https://help.squarecloud.app/pt-br/article/como-configurar-seu-proprio-dominio-cnamedns-j39hh2/">
    Sirva a sua aplicação no seu próprio domínio, a partir do plano Standard.
  </Card>

  <Card title="Solução de problemas" icon="wrench" href="/pt-br/platform/troubleshooting">
    Corrija uma aplicação que não inicia ou um site que não responde.
  </Card>
</CardGroup>

## Contate-nos

Se você continuar enfrentando **dificuldades técnicas**, nossa **equipe de suporte especializada** está disponível para auxiliá-lo. [**Entre em contato conosco**](https://squarecloud.app/pt-br/support) e teremos prazer em ajudá-lo a resolver qualquer questão: a qualidade do suporte é uma grande parte do motivo pelo qual desenvolvedores avaliam a Square Cloud com [**4,9/5 em 402 avaliações**](https://www.trustpilot.com/review/squarecloud.app) no Google e Trustpilot.


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