Guia de Início Rápido

Bem-vindo a Trapiche! Esta documentação vai te ensinar como fazer deploy de sites estáticos em minutos.

O que é a Trapiche?

Trapiche é uma plataforma de deploy otimizada para o Brasil. Faça deploy de seus projetos Next.js, Astro, React, Vite e outros frameworks diretamente do GitHub com:

Deploy automático a cada push (webhooks do GitHub)
Domínios personalizados com SSL automático
Infraestrutura 100% brasileira (baixa latência)
Armazenamento e servidores seguros no Brasil
Detecção automática de framework (Next.js, Astro, Vite, CRA e mais)
Interface intuitiva e moderna

Pré-requisitos

Antes de começar, você precisa ter:

Uma conta no GitHub
Um repositório com seu projeto web (Next.js, React, Vite, Astro, etc.)
Para Next.js: Use output: 'export' no seu next.config.js (exportação estática)

Seu Primeiro Deploy

Acesse a plataforma Trapiche e faça login com sua conta do GitHub.

https://dashboard.trapiche.cloud/login

A autenticação é feita via GitHub OAuth, então você não precisa criar uma senha separada.

2. Crie um Novo Deploy

No dashboard, clique em “Novo Deploy”
Selecione o repositório do GitHub que deseja fazer deploy ou cole uma URL
A branch padrao e a main ou master;
Clique em “Deploy”

3. Aguarde o Build

A Trapiche irá automaticamente:

Clonar seu repositório
Detectar o framework (Next.js, Vite, React, etc.)
Instalar as dependências (npm install)
Executar o build (npm run build)
Fazer upload dos arquivos para o armazenamento

Você pode acompanhar o progresso em tempo real através dos logs de build.

4. Acesse Seu Site

Após o deploy ser concluído com sucesso, seu site estará disponível em:

https://seu-projeto-xyz123.trapiche.site

A Trapiche gera automaticamente um URL único para cada deploy.

Deploy Automático (Webhooks)

Todo app na Trapiche possui deploy automático sempre que você fizer push no GitHub. A Trapiche registra um webhook no seu repositório do GitHub automaticamente.

Adicionar Domínio Personalizado (Opcional)

Quer usar seu próprio domínio? É simples:

Passo 1: Adicione o Domínio

Acesse os detalhes do seu deploy
Clique em “Adicionar Domínio”
Digite seu domínio (ex: meusite.com.br)

A Trapiche irá gerar um token de verificação.

Passo 2: Configure o DNS

No painel de controle do seu provedor de domínio, adicione os seguintes registros:

Registro TXT (para verificação):

Nome: _trapiche-verification.meusite.com.br
Valor: trapiche-verify=SEU_TOKEN_AQUI

Registro CNAME (para apontar o domínio):

Nome: @ (ou meusite.com.br)
Valor: cname.trapiche.cloud

Passo 3: Verifique o Domínio

Aguarde alguns minutos para a propagação do DNS (pode levar até 48 horas)
Na Trapiche, clique em “Verificar Domínio”
A Trapiche irá verificar os registros DNS
Após a verificação, o SSL será provisionado automaticamente (leva ~30 segundos)

Pronto! Seu site agora está disponível em https://meusite.com.br com SSL automático.

Frameworks Suportados

A Trapiche detecta automaticamente o framework do seu projeto a partir do package.json e configura o build sem nenhuma intervenção manual.

Next.js

A Trapiche suporta Next.js no modo de exportação estática. Certifique-se de configurar o output: 'export' no seu arquivo de configuração:

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  // ... outras configurações
}

module.exports = nextConfig

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  output: 'export',
}

export default nextConfig

A Trapiche aceita next.config.js, next.config.mjs e next.config.ts.

Diretório de build: out

Limitações do modo estático:

Rotas de API (/api/*) não são geradas
getServerSideProps não é suportado (use getStaticProps)
Middleware não funciona em produção

SSR (Server-Side Rendering): Next.js SSR também é suportado via Docker. Se o seu next.config.* não tiver output: 'export', a Trapiche detecta automaticamente o modo SSR e faz o deploy em *.ssr.trapiche.cloud com output: 'standalone'.

Exemplos: example-nextjs-static · example-nextjs-ssr

Deploy na Trapiche

Astro

A Trapiche suporta projetos Astro no modo de saída estática (padrão).

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static', // padrão — pode omitir
});

Se você usar um outDir personalizado, a Trapiche o detecta automaticamente:

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static',
  outDir: './public-build', // detectado automaticamente
});

Diretório de build: dist (ou o valor de outDir se configurado)

O Astro é compatível com qualquer UI framework em modo estático: React, Vue, Svelte, Solid, Preact, etc.

Modo server: output: 'server' não é suportado no momento.

Exemplo: example-astro-static

Deploy na Trapiche

Vite

A Trapiche detecta qualquer projeto Vite pela presença de "vite" no package.json. Funciona com todos os templates oficiais do Vite:

Template	Comando de criação
React	`npm create vite@latest meu-app -- --template react`
React + TypeScript	`npm create vite@latest meu-app -- --template react-ts`
Vue 3	`npm create vite@latest meu-app -- --template vue`
Svelte	`npm create vite@latest meu-app -- --template svelte`
Preact	`npm create vite@latest meu-app -- --template preact`
Vanilla JS	`npm create vite@latest meu-app -- --template vanilla`

Nenhuma configuração extra é necessária. O comando npm run build e o diretório de saída dist são detectados automaticamente.

Diretório de build: dist

Exemplo: example-vite-react

Deploy na Trapiche

Create React App

Detectado pela presença de "react-scripts" no package.json. Projetos criados com npx create-react-app funcionam sem nenhuma configuração adicional.

npx create-react-app meu-app
cd meu-app
# faça o deploy diretamente — nenhuma configuração necessária

Diretório de build: build

Exemplo: example-cra

Deploy na Trapiche

Sites Estáticos Genéricos

Qualquer projeto com um script build no package.json que gere arquivos estáticos é suportado. Isso inclui Hugo, Eleventy, Gatsby (modo estático), e qualquer outro gerador de sites.

{
  "scripts": {
    "build": "seu-comando-de-build"
  }
}

Diretório de build: dist

SvelteKit

A Trapiche suporta SvelteKit via Docker. Configure o adaptador Node.js no seu projeto:

npm install -D @sveltejs/adapter-node

// svelte.config.js
import adapter from '@sveltejs/adapter-node';

export default {
  kit: {
    adapter: adapter()
  }
};

{
  "scripts": {
    "build": "vite build",
    "start": "node build"
  }
}

Exemplo: example-sveltekit

Deploy na Trapiche

URL do deploy: https://seu-app.ssr.trapiche.cloud

Elysia (Bun)

A Trapiche suporta Elysia via Docker com Bun. Certifique-se de ter um script start no package.json:

// src/index.ts
import { Elysia } from 'elysia'

const app = new Elysia()
  .get('/', () => 'Hello!')
  .listen(process.env.PORT ?? 3000)

{
  "scripts": {
    "start": "bun src/index.ts"
  }
}

A Trapiche detecta o uso de Bun e gera o Dockerfile automaticamente — nenhuma configuração extra é necessária.

URL do deploy: https://seu-app.ssr.trapiche.cloud

Node.js (Express, Fastify, Koa, Hono)

A Trapiche suporta backends Node.js via Docker. O app é containerizado e servido em *.ssr.trapiche.cloud.

Requisitos:

Um script start no package.json que inicie o servidor
O servidor deve escutar na variável de ambiente PORT (a Trapiche injeta a porta automaticamente)

// server.js (Express)
const express = require('express')
const app = express()
const port = process.env.PORT || 3000

app.get('/', (req, res) => res.send('Hello!'))

app.listen(port)

{
  "scripts": {
    "start": "node server.js"
  }
}

A Trapiche gera automaticamente o Dockerfile para Express, Fastify, Koa e Hono — você não precisa criar um. Caso queira personalizar, basta incluir um Dockerfile na raiz do repositório.

Exemplos: example-express · example-fastify · example-koa · example-hono

Deploy na Trapiche

URL do deploy: https://seu-app.ssr.trapiche.cloud

Dockerfile

Se o seu projeto usa uma linguagem ou runtime que a Trapiche não detecta automaticamente, basta incluir um Dockerfile na raiz do repositório. A Trapiche detecta o Dockerfile e faz o build e deploy do container automaticamente.

Requisitos:

Um Dockerfile na raiz do repositório
O container deve escutar na variável de ambiente PORT (a Trapiche injeta a porta automaticamente)
Use EXPOSE para declarar a porta no Dockerfile

FROM python:3.12-alpine

WORKDIR /app

COPY main.py .

EXPOSE 3000
ENV PORT=3000

CMD ["python", "main.py"]

Funciona com qualquer linguagem ou runtime: Python, Go, Rust, Java, PHP, Ruby, etc. — se roda em um container, roda na Trapiche.

Exemplo: example-python-dockerfile

Deploy na Trapiche

URL do deploy: https://seu-app.ssr.trapiche.cloud

Frameworks Não Suportados

Os seguintes frameworks não são suportados no momento:

Astro em modo server (output: 'server') — use output: 'static'
NestJS
Nuxt
Remix
SolidStart
Qwik
TanStack Start

Redeploy Manual

Para fazer um novo deploy sem fazer push no GitHub:

Acesse os detalhes do seu deploy
Clique em “Redeploy”
A Trapiche irá reclonar o repositório e refazer o build

Útil para testar mudanças ou quando o auto-deploy está desativado.

Próximos Passos

Agora que você fez seu primeiro deploy, explore mais funcionalidades:

Logs de Build: Acesse logs detalhados de cada deploy
Múltiplos Deploys: Gerencie vários projetos em uma única conta
Múltiplos Domínios: Adicione vários domínios ao mesmo deploy
Repositórios Privados: A Trapiche suporta repos privados automaticamente

Troubleshooting

Build falha com “app requires server-side rendering”

Este erro é temporário — a Trapiche tenta primeiro o build estático e, ao detectar SSR, refaz automaticamente como Docker. Se o build continuar falhando:

Next.js: Verifique se o projeto não tem output: 'export' no next.config.js (se quiser SSR, remova ou use output: 'standalone')
Astro: output: 'server' não é suportado — use output: 'static'
Express / Fastify / Koa / Elysia: Certifique-se de ter um script start no package.json e que o servidor escuta na variável PORT

Build falha com “not static” (Next.js)

Se você receber este erro em um projeto Next.js:

Certifique-se de usar output: 'export' no next.config.js
Verifique se não está usando getServerSideProps ou rotas de API (incompatíveis com exportação estática)

Verificação de domínio falha

A propagação de DNS pode levar até 48 horas
Verifique os registros com: dig @8.8.8.8 _trapiche-verification.seudominio.com.br TXT
Certifique-se de que o registro A aponta para cname.trapiche.cloud

Deploy está demorando muito

Builds normalmente levam de 1 a 5 minutos, dependendo do tamanho do projeto. Se estiver demorando mais:

Verifique os logs de build para erros
Certifique-se de que o package.json está correto
Verifique se não há dependências quebradas

Suporte

Precisa de ajuda? Entre em contato:

Email: suporte@trapiche.cloud
Discord: discord.gg/trapiche

Feito com ❤️ no Brasil 🇧🇷

Guia de Início Rápido

O que é a Trapiche?

Pré-requisitos

Seu Primeiro Deploy

1. Faça Login

2. Crie um Novo Deploy

3. Aguarde o Build

4. Acesse Seu Site

Deploy Automático (Webhooks)

Adicionar Domínio Personalizado (Opcional)

Passo 1: Adicione o Domínio

Passo 2: Configure o DNS

Passo 3: Verifique o Domínio

Frameworks Suportados

Next.js

Astro

Vite

Create React App

Sites Estáticos Genéricos

SvelteKit

Elysia (Bun)

Node.js (Express, Fastify, Koa, Hono)

Dockerfile

Frameworks Não Suportados

Redeploy Manual

Próximos Passos

Troubleshooting

Build falha com “app requires server-side rendering”

Build falha com “not static” (Next.js)

Verificação de domínio falha

Deploy está demorando muito

Suporte