Faça deploy de uma API NestJS

Introdução

Para desenvolver e hospedar uma aplicação NestJS na Square Cloud, siga a sequência de configurações e pré-requisitos abaixo. Este guia cobre todo o processo, da configuração inicial ao deploy em produção.

Pré-requisitos

Conta Square Cloud: Cadastre-se através da página de cadastro usando seu e-mail.
Plano ativo: Garante recursos dedicados e desempenho otimizado para seu aplicativo. Confira nossos planos disponíveis e escolha o mais adequado às suas necessidades.

Este guia usa o runtime Node.js. Testado com NestJS 12 no Node.js 24 em setembro de 2026.

Crie o projeto

Você precisa do Node.js e do npm na sua máquina. Se ainda não os tiver, baixe-os no site oficial do Node.js. Instale a Nest CLI globalmente e crie um projeto:

npm install -g @nestjs/cli
nest new my-app

O nest new pergunta qual gerenciador de pacotes usar e instala as dependências na nova pasta my-app. Inicie o servidor de desenvolvimento com npm run start:dev; ele escuta em http://localhost:3000.

Faça o build para produção

O NestJS é escrito em TypeScript, então compile-o para JavaScript antes do deploy:

npm run build

O script build executa o nest build, que grava os arquivos compilados na pasta dist/. O arquivo de entrada é o dist/main.js, o mesmo arquivo que o script start:prod executa.

Não use nest start nem npm run start em produção. A Nest CLI e o TypeScript são devDependencies, que a Square Cloud não instala (ela roda com NODE_ENV=production). Faça o build na sua máquina e envie a pasta dist/ compilada.

Porta e host

Nada a mudar: o src/main.ts gerado já lê a variável de ambiente PORT, que a Square Cloud define como 80, e o Nest escuta em todas as interfaces de rede por padrão. Localmente, ele usa a porta 3000:

src/main.ts

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module.js';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT ?? 3000);
}
await bootstrap();

Projetos criados com versões mais antigas da Nest CLI podem importar ./app.module e terminar com bootstrap();. A linha que importa é a do app.listen.

Configure a Square Cloud

Crie um arquivo squarecloud.app na raiz do projeto:

squarecloud.app

MAIN=dist/main.js
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My NestJS API
SUBDOMAIN=my-nest-api

A Square Cloud então executa node dist/main.js, o mesmo comando do script start:prod. No upload pelo dashboard, defina o dist/main.js como arquivo principal.

O que vai no ZIP

dist/, a aplicação compilada.
package.json.
squarecloud.app.

Deixe de fora a node_modules: a Square Cloud instala as suas dependencies na primeira inicialização.

Faça o deploy e verifique

Via dashboard

Acesse a página de upload

Acesse a página de upload e envie seu arquivo zip.

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.

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.

Confirme que seu app está no ar

Seu primeiro deploy geralmente leva menos de um minuto. No 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.

Seu app não está iniciando? Veja o guia de solução de problemas para as causas e correções mais comuns.

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.

Guia do arquivo de configuração

Saiba como criar o arquivo de configuração squarecloud.app que define o ambiente da sua aplicação.

Instale a CLI

Instale a CLI da Square Cloud. Se você já a tem, execute o mesmo comando para atualizá-la:

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

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.

squarecloud auth login

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 lista, e faz o upload:

squarecloud upload

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

squarecloud upload --file <caminho/para/zip>

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:

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.

Seu app não está iniciando? Veja o guia de solução de problemas para as causas e correções mais comuns.

Erros comuns

Domínio personalizado

Para usar um domínio personalizado (ex.: meusite.com) no lugar da URL padrão meusite.squareweb.app, você precisa do plano Standard ou superior. A URL padrão vem do campo SUBDOMAIN no arquivo de configuração. Para conectar o seu domínio, veja como configurar seu próprio domínio.

Requisitos mínimos de RAM

Mínimo: 512MB de RAM para sites e APIs, o suficiente para um build estático no runtime estático. Para aplicações que renderizam páginas no servidor (Next.js, Nuxt, Angular SSR e similares), recomendamos pelo menos 1GB de RAM. Para aplicações maiores, aloque mais RAM para evitar que a aplicação fique sem memória e trave.

Não foi possível encontrar esse site.

Verifique se o subdomínio/domínio corresponde ao configurado no campo SUBDOMAIN ou nas configurações de domínio personalizado. Se você acabou de enviar o site, aguarde até 60 segundos para a Square liberar o primeiro acesso.

Site demorou demais para responder…

O seu servidor precisa escutar na porta 80 e no host 0.0.0.0. A Square Cloud define as variáveis de ambiente PORT (80) e HOST (0.0.0.0) na sua aplicação: leia essas variáveis no código em vez de fixar outros valores. Um servidor que escuta apenas em localhost ou 127.0.0.1 nunca recebe requisições.

O arquivo principal é inválido ou está corrompido

O dist/main.js está faltando no ZIP. Execute npm run build e confira se a pasta dist/ está na raiz do ZIP.

Próximos passos

Variáveis de ambiente

Mantenha segredos e configurações fora do código e leia-os em tempo de execução.

Domínio personalizado

Sirva a sua aplicação no seu próprio domínio, a partir do plano Standard.

Solução de problemas

Corrija uma aplicação que não inicia ou um site que não responde.

Para saber mais sobre o NestJS, consulte a documentação oficial do NestJS.

Contate-nos

Se você continuar enfrentando dificuldades técnicas, nossa equipe de suporte especializada está disponível para auxiliá-lo. Entre em contato conosco 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 no Google e Trustpilot.

Bots

Sites

APIs e backends

Bancos de dados

Aplicações self-hosted

Guias

Guias de migração

Faça deploy de uma API NestJS

Introdução

Pré-requisitos

Crie o projeto

Faça o build para produção

Porta e host

Configure a Square Cloud

O que vai no ZIP

Faça o deploy e verifique

Via dashboard

Via CLI

Guia do arquivo de configuração

Erros comuns

Domínio personalizado

Requisitos mínimos de RAM

Não foi possível encontrar esse site.

Site demorou demais para responder…

O arquivo principal é inválido ou está corrompido

Próximos passos

Variáveis de ambiente

Domínio personalizado

Solução de problemas

Contate-nos

​Introdução

​Pré-requisitos

​Crie o projeto

​Faça o build para produção

​Porta e host

​Configure a Square Cloud

​O que vai no ZIP

​Faça o deploy e verifique

​Via dashboard

​Via CLI

Guia do arquivo de configuração

​Erros comuns

​Domínio personalizado

​Requisitos mínimos de RAM

​Não foi possível encontrar esse site.

​Site demorou demais para responder…

​O arquivo principal é inválido ou está corrompido

​Próximos passos

Variáveis de ambiente

Domínio personalizado

Solução de problemas

​Contate-nos

Introdução

Pré-requisitos

Crie o projeto

Faça o build para produção

Porta e host

Configure a Square Cloud

O que vai no ZIP

Faça o deploy e verifique

Via dashboard

Via CLI

Erros comuns

Domínio personalizado

Requisitos mínimos de RAM

Não foi possível encontrar esse site.

Site demorou demais para responder…

O arquivo principal é inválido ou está corrompido

Próximos passos

Contate-nos