Como hospedar aplicações Remix na Square Cloud

O Remix virou React Router (v7+). Para projetos novos, o start é react-router-serve ./build/server/index.js; projetos Remix v2 com Vite seguem com remix-serve ./build/server/index.js (com @remix-run/serve em dependencies). A Square Cloud não instala devDependencies (NODE_ENV=production), então o build precisa ser feito localmente. Para rodar sua aplicação na Square Cloud, o fluxo padrão envolve compilar o projeto para produção e utilizar a ferramenta nativa remix-serve para gerenciar as requisições na porta correta.

1. O Processo de Build

Antes de enviar sua aplicação para o ambiente de produção, você precisa compilar o código fonte. Esse processo otimiza suas rotas, componentes React e compila os arquivos do servidor.

No terminal do seu projeto local, execute:

npm run build

Por padrão (especialmente em versões modernas baseadas no Vite), o Remix gerará a pasta build/ contendo o servidor compilado e os assets do cliente.

2. Configurando o Comando de Início (remix-serve)

Diferente de servidores Node customizados, o Remix fornece um pacote pronto chamado remix-serve para rodar a aplicação construída na pasta de build.

Use um arquivo de configuração squarecloud⁠.app com RUNTIME=nodejs, START=npm run start (script que roda remix-serve/react-router-serve), MEMORY, VERSION=recommended, DISPLAY_NAME e SUBDOMAIN. Só com START, sem MAIN nem RUNTIME, o deploy falha com MISSING_MAIN. No dashboard, marque Publicação na Web já no primeiro envio. O script start deve invocar esse utilitário:

npx remix-serve ./build/server/index.js

(Nota: Certifique-se de validar o caminho exato do arquivo index.js gerado na sua pasta build, que pode variar levemente dependendo da sua versão do Remix ou arquivo de configuração do Vite).

3. O que incluir no pacote de envio (.zip)?

Para garantir um deploy rápido, limpo e sem problemas de armazenamento, crie um arquivo .zip contendo apenas os artefatos de produção:

• A pasta build/ (Gerada pelo comando de build).
• A pasta public/ (Contém seus assets estáticos, como imagens e favicon).
• O arquivo package.json.
• O arquivo package-lock.json ou yarn.lock.

Atenção: Nunca inclua a pasta node_modules no seu arquivo compactado. A Square Cloud fará uma instalação isolada e limpa das dependências diretamente no servidor após o upload.

4. Dicas de Produção

• Vite Versão: Se você migrou recentemente o seu projeto Remix para o compilador do Vite, certifique-se de que seu arquivo vite.config.ts está configurado corretamente para produção.
• Variáveis do Lado do Servidor: Lembre-se de que chaves de API secretas e strings de conexão com bancos de dados nunca devem ficar expostas no código. Adicione-as todas na aba de Variáveis de Ambiente no painel da Square Cloud. O Remix as acessará nativamente através de process.env.

Atualizado em: 04/10/2026