Guia completo para implantar aplicações frontend no Cloudflare Pages: configuração de React/Vue/Next.js e solução de erros

Introdução

Você terminou um projeto React e quer colocá-lo no ar. Então abre a página de configuração do Cloudflare Pages e fica olhando para os campos “Build Command” e “Build Output Directory” sem saber o que preencher. O comando é npm run build ou npm build? O diretório de saída é build ou dist? E como configurar as variáveis de ambiente?

Este artigo mostra, passo a passo, como implantar projetos React, Vue e Next.js no Cloudflare Pages: checklist completo de configuração, variáveis de ambiente e soluções para cinco erros comuns — com atenção especial ao nodejs_compat no Next.js.

Por que escolhi o Cloudflare Pages?

Talvez você se pergunte: se já existem Vercel e Netlify, por que usar o Cloudflare Pages?

No começo, eu também usava o Vercel. Não porque o Vercel seja ruim, mas porque o plano gratuito realmente tem algumas limitações. Com alguns projetos pequenos, ultrapassei 100 GB de tráfego no mês e o Vercel começou a limitar a velocidade.

Depois de comparar as três plataformas, percebi que o plano gratuito do Cloudflare Pages é muito vantajoso:

Como dá para ver, o tráfego ilimitado por si só já é muito atraente. Hoje hospedo vários projetos pessoais no CF Pages e não preciso me preocupar com tráfego.

Cenários indicados para o Cloudflare Pages:

• Blogs pessoais e portfólios
• Projetos frontend pequenos e médios (SPA e sites estáticos)
• Projetos que precisam de aceleração global
• Projetos com tráfego imprevisível (tráfego gratuito ilimitado faz diferença)

Cenários menos indicados:

• Aplicações Next.js grandes que exigem recursos SSR complexos (o suporte do CF Pages ao Next.js não é tão completo quanto o do Vercel)
• Projetos que exigem builds frequentes (limite de 500 builds por mês)
• Projetos que dependem de recursos exclusivos do Vercel, como Edge Middleware

Preparação antes da implantação

Antes de começar, você precisa:

1. Criar uma conta Cloudflare
   • Cadastre-se gratuitamente no site oficial do Cloudflare
   • Depois de verificar o e-mail, você já pode começar
2. Preparar o repositório do código
   • Envie o código para o GitHub ou GitLab
   • O CF Pages buscará o código diretamente no seu repositório Git para fazer o build
3. Conhecer a configuração de build do projeto
   • Você usa Create React App ou Vite?
   • Qual é o comando de build? Normalmente, npm run build
   • Em qual diretório ficam os artefatos? No CRA é build; no Vite, dist

Com tudo preparado, vamos partir para a implantação.

Processo completo para implantar uma aplicação React

React é um dos frameworks frontend mais usados. Depois de implantar vários projetos React no CF Pages, organizei um checklist de configuração confiável.

Criar rapidamente um projeto React (caso você ainda não tenha um)

Se quiser acompanhar o tutorial, mas ainda não tiver um projeto pronto, crie um rapidamente:

# Opção 1: usar Vite (recomendado, build mais rápido)
npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install
# Opção 2: usar Create React App (forma clássica)
npx create-react-app my-react-app
cd my-react-app

Eu prefiro o Vite, porque o build é bem mais rápido. Conforme um projeto CRA cresce, o build costuma ficar lento.

Checklist de configuração do Cloudflare Pages

Entre no Cloudflare Dashboard, acesse Pages, clique em “Create a project” → “Connect to Git” e selecione seu repositório do GitHub.

Em seguida, você verá a página de configuração. Esta é a parte essencial:

Campos de configuração:

Atenção:

• No projeto Vite, basta selecionar “None” em Framework preset; o CF Pages fará a detecção automática
• No projeto CRA, você pode escolher o preset “Create React App”, que preenche a configuração automaticamente
• O diretório de saída é o erro mais comum: no Vite é dist; no CRA é build. Não troque os dois

Configurar variáveis de ambiente

As variáveis de ambiente em projetos React têm uma exigência especial: para serem acessadas no cliente, precisam ter um prefixo específico.

Projeto Vite:

• O prefixo deve ser VITE_
• Exemplos: VITE_API_URL e VITE_API_KEY

Projeto CRA:

• O prefixo deve ser REACT_APP_
• Exemplos: REACT_APP_API_URL e REACT_APP_API_KEY

Como configurar:

1. No Cloudflare Pages (recomendado):
   • Acesse o projeto → Settings → Environment variables
   • Clique em “Add variable”
   • Escolha o ambiente: Production ou Preview
   • Informe o nome e o valor da variável
2. No código:

// Projeto Vite
const apiUrl = import.meta.env.VITE_API_URL;
// Projeto CRA
const apiUrl = process.env.REACT_APP_API_URL;

Variáveis de ambiente no desenvolvimento local:

Crie um arquivo .env.local na raiz do projeto:

# Projeto Vite
VITE_API_URL=https://api.example.com
VITE_API_KEY=your-api-key-here
# Projeto CRA
REACT_APP_API_URL=https://api.example.com
REACT_APP_API_KEY=your-api-key-here

Lembretes importantes:

• Não envie o arquivo .env.local ao Git. Adicione .env*.local ao .gitignore
• Depois de alterar uma variável de ambiente, é preciso fazer uma nova implantação

Resolver erro 404 em rotas SPA

Se o projeto React usa React Router, você pode encontrar um problema depois da implantação: ao atualizar uma página, ela retorna 404.

Isso acontece porque todas as rotas de uma SPA precisam apontar para index.html, mas, por padrão, o servidor procura um arquivo correspondente à rota.

Solução:

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Crie um arquivo _redirects no diretório public do projeto:

/* /index.html 200

Essa única linha instrui o servidor a redirecionar todos os caminhos para index.html e retornar o status 200.

Salve e faça uma nova implantação. As rotas passarão a funcionar normalmente.

Verificar se a implantação foi concluída

Depois de clicar em “Save and Deploy”, o CF Pages iniciará o build. Você pode acompanhar o log na página “Deployments”.

Sinais de que o build foi concluído:

• O log mostra “Success: Deployed to…”
• Você recebe um link xxx.pages.dev
• Ao abrir o link, seu projeto aparece

Se o build falhar:

• Consulte o log para localizar a mensagem de erro
• Causas comuns:
  • Diretório de saída incorreto (usar build no Vite ou dist no CRA)
  • Versão do Node muito antiga (defina a variável de ambiente NODE_VERSION=18)
  • Falha ao instalar dependências (verifique package.json)

Processo completo para implantar uma aplicação Vue

A implantação do Vue é parecida com a do React, mas há alguns detalhes importantes.

Criar rapidamente um projeto Vue (opcional)

# Opção 1: usar Vite (recomendado)
npm create vite@latest my-vue-app -- --template vue
cd my-vue-app
npm install
# Opção 2: usar Vue CLI
vue create my-vue-app
cd my-vue-app

Aqui também recomendo o Vite, por ter melhor desempenho.

Checklist de configuração do Cloudflare Pages

Lembretes importantes:

• Tanto o Vue CLI quanto o Vite usam dist como diretório de saída — diferente do que acontece entre Vite e CRA no React
• Os prefixos das variáveis são diferentes: VITE_ no Vite e VUE_APP_ no Vue CLI

Configurar variáveis de ambiente

Projeto Vite + Vue:

# .env.local
VITE_API_BASE_URL=https://api.example.com
VITE_APP_TITLE=My Vue App

Projeto Vue CLI:

# .env.production
VUE_APP_API_BASE_URL=https://api.example.com
VUE_APP_TITLE=My Vue App

Uso no código:

// Projeto Vite
const apiUrl = import.meta.env.VITE_API_BASE_URL;
// Projeto Vue CLI
const apiUrl = process.env.VUE_APP_API_BASE_URL;

Configurar rotas do Vue Router

Se você usa Vue Router, principalmente no modo History, precisa configurar o redirecionamento. Caso contrário, atualizar uma página resultará em 404.

Opção 1: arquivo _redirects (recomendado)

Crie _redirects no diretório public:

/* /index.html 200

Opção 2: configurar vite.config.js (projeto Vite)

Se o projeto não for implantado na raiz, configure base:

// vite.config.js
export default {
  base: '/', // Confirme que é o caminho raiz
}

Solução de problemas comuns

Problema 1: arquivos estáticos retornam 404

Confira publicPath ou base em vue.config.js (Vue CLI) ou vite.config.js (Vite):

// vue.config.js (Vue CLI)
module.exports = {
  publicPath: '/', // Confirme que é o caminho raiz
}

Problema 2: erro “Unknown file extension” no build do Vite

Normalmente, isso acontece porque a versão do Node é muito antiga. Adicione esta variável de ambiente no CF Pages:

NODE_VERSION=18

Depois, faça uma nova implantação.

Processo completo para implantar uma aplicação Next.js (atenção especial)

Para ser sincero, implantar Next.js no Cloudflare Pages é o processo mais complexo entre os três frameworks. Na primeira vez que fiz isso, passei uma tarde inteira preso ao erro de nodejs_compat e precisei pesquisar bastante até resolver.

Falando francamente, se o projeto Next.js exige muitos recursos SSR, eu ainda recomendo o Vercel. Mas, para sites estáticos ou SSR simples, o CF Pages atende muito bem — e o tráfego gratuito ilimitado é um grande benefício.

Particularidades da implantação do Next.js

Antes de começar, você precisa saber alguns pontos importantes:

1. O Cloudflare Pages não foi criado especificamente para Next.js, ao contrário do Vercel, e exige algumas configurações extras
2. Há duas formas de implantação: exportação estática (a mais simples) e modo SSR (que exige um adaptador)
3. Para usar SSR, é necessário o adaptador @opennextjs/cloudflare; o antigo @cloudflare/next-on-pages foi descontinuado

Opção 1: exportação estática (mais simples e recomendada para iniciantes)

Se o projeto Next.js não precisa de renderização no servidor, API Routes, ISR ou recursos semelhantes, a exportação estática é a solução mais simples.

Cenários indicados:

• Blogs pessoais
• Sites de documentação
• Sites exclusivamente informativos
• Projetos sem dados dinâmicos

Etapas de configuração:

1. Altere next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // Essencial: ativa a exportação estática
  images: {
    unoptimized: true, // O CF Pages não oferece suporte ao Image Optimization do Next.js
  },
}
module.exports = nextConfig

2. Configure o Cloudflare Pages:

3. Faça a implantação:

Salve a configuração e implante o projeto. Quando o build terminar, você terá um site estático.

Limitações:

• ❌ Não oferece suporte a API Routes
• ❌ Não oferece suporte a ISR (Incremental Static Regeneration)
• ❌ Não oferece suporte a Server Components
• ❌ Não oferece renderização no servidor para rotas dinâmicas

Se essas limitações forem aceitáveis, a exportação estática será suficiente.

Opção 2: modo SSR (com o adaptador OpenNext)

Se você precisa de API Routes, SSR, rotas dinâmicas e outros recursos, terá que usar um adaptador. Esta parte é um pouco mais complexa, mas vou detalhá-la da forma mais clara possível.

Instale o adaptador:

npm install @opennextjs/cloudflare

Configure next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Não é necessário definir output: 'export'
  images: {
    unoptimized: true,
  },
}
module.exports = nextConfig

Configure o Cloudflare Pages:

Atenção: configure as Compatibility Flags — este é o ponto que mais causa erros:

Esta etapa é essencial, e muita gente fica presa nela. Na minha primeira implantação, não configurei a flag e recebia continuamente o erro nodejs_compat is not defined.

1. Acesse seu projeto → Settings → Functions
2. Localize a seção Compatibility flags
3. Clique em Configure Production compatibility flag
4. Adicione a flag nodejs_compat
5. Defina Compatibility Date como, no mínimo, 2024-09-23 ou uma data posterior

Atenção:

• É preciso configurar os ambientes Production e Preview
• Sem essa flag, a aplicação retornará erro 500 após a implantação

Requisito de Edge Runtime:

Se você usa API Routes ou Server Components, precisa adicionar a declaração de Edge Runtime:

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

// app/api/hello/route.js
export const runtime = 'edge'; // Essencial: adicione esta linha
export async function GET(request) {
  return new Response(JSON.stringify({ message: 'Hello from CF Pages' }), {
    headers: { 'content-type': 'application/json' },
  });
}

// pages/api/hello.js (Pages Router)
export const config = {
  runtime: 'edge', // Essencial: adicione esta linha
};
export default function handler(req) {
  return new Response(JSON.stringify({ message: 'Hello from CF Pages' }), {
    headers: { 'content-type': 'application/json' },
  });
}

Todo arquivo que precisa ser executado no servidor deve ter essa declaração. Sem ela, a implantação falhará.

Configurar variáveis de ambiente no Next.js

As variáveis de ambiente do Next.js se dividem em dois tipos:

1. Variáveis do cliente (prefixo obrigatório):

# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_SITE_NAME=My Next.js Site

2. Variáveis do servidor (sem prefixo):

# .env.local
DATABASE_URL=postgresql://...
API_SECRET=your-secret-key

Configuração no Cloudflare Pages:

Acesse Settings → Environment variables e, ao adicionar cada variável, escolha o ambiente correspondente: Production ou Preview.

Uso no código:

// Cliente
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
// Servidor (API Route ou Server Component)
const dbUrl = process.env.DATABASE_URL;

Erros comuns do Next.js e como resolvê-los (atenção especial)

Esta seção reúne cinco dos erros mais comuns que encontrei e as respectivas soluções.

Erro 1: nodejs_compat is not defined ou erro 500

Mensagem de erro:

Error: The global scope does not support nodejs_compat

Ou a implantação termina com sucesso, mas a página retorna erro 500.

Causa:

A flag de compatibilidade nodejs_compat está ausente.

Solução:

1. Acesse o projeto → Settings → Functions
2. Localize Compatibility flags
3. Adicione nodejs_compat aos ambientes Production e Preview
4. Faça uma nova implantação

Fiquei preso nesse problema por bastante tempo. Assim que configurei a flag, tudo funcionou.

Erro 2: a implantação termina com sucesso, mas a página mostra 404

Sintomas:

• O log de build indica sucesso
• xxx.pages.dev retorna 404
• Ou apenas a página inicial funciona; as demais retornam 404

Causas:

• Edge Runtime não foi configurado corretamente
• Ou Build output directory está incorreto

Solução:

1. Confira se todas as API Routes e todos os Server Components declaram runtime = 'edge'
2. Confirme se Build output directory é .worker-next com o adaptador ou out na exportação estática
3. Na exportação estática, confirme se o arquivo _redirects foi criado

Erro 3: FinalizationRegistry is not defined

Mensagem de erro:

ReferenceError: FinalizationRegistry is not defined

Causa:

Compatibility Date é antiga demais e não oferece suporte a recursos mais novos do JavaScript.

Solução:

1. Acesse Settings → Functions
2. Atualize Compatibility Date para 2024-09-23 ou uma data posterior
3. Faça uma nova implantação

Erro 4: build muito demorado ou com falha

Sintomas:

• O build continua por mais de 10 minutos
• Ou aparece “Build exceeded maximum duration”

Causas:

• Uso do Turbopack (next dev --turbo)
• Ou o projeto é grande e tem dependências demais

Solução:

1. Confira Build command e use npx @opennextjs/cloudflare, sem o parâmetro --turbo
2. Remova dependências desnecessárias com npm prune
3. Se possível, considere usar a exportação estática

Erro 5: falha no Image Optimization

Mensagem de erro:

Error: Image Optimization using Next.js' default loader is not compatible with `output: 'export'`.

Causa:

O Cloudflare Pages não oferece suporte à API de Image Optimization do Next.js.

Solução:

Desative o recurso em next.config.js:

module.exports = {
  images: {
    unoptimized: true,
  },
}

Se você precisar otimizar imagens, pode usar:

• Cloudflare Images (serviço pago)
• Uma CDN de terceiros, como Cloudinary
• Processamento próprio das imagens, com compressão antes do envio

Gerenciamento avançado de variáveis de ambiente

No começo, também achei confuso gerenciar variáveis de ambiente, principalmente para diferenciar desenvolvimento, preview e produção. Com o tempo, cheguei a uma forma mais clara de organizar tudo.

Diferenciar os três ambientes

O Cloudflare Pages oferece três ambientes:

Configurar no Cloudflare Dashboard

Acesse o projeto → Settings → Environment variables.

Você verá duas abas:

• Production: variáveis do ambiente de produção
• Preview: variáveis do ambiente de preview

Configuração recomendada:

1. Variáveis do ambiente de produção, como API Keys reais e conexões de banco de dados:
   • Escolha o tipo Secret, que armazena os dados criptografados e não os exibe no log
   • Exemplo: API_KEY=prod-key-12345
2. Variáveis do ambiente de preview, como API Keys de teste:
   • Você pode escolher Plain text
   • Exemplo: API_KEY=test-key-67890

Variáveis de ambiente para desenvolvimento local

Estrutura de arquivos recomendada:

my-project/
├── .env.local          # Variáveis locais (não enviar ao Git)
├── .env.example        # Modelo de variáveis (enviar ao Git)
├── .gitignore          # Ignora arquivos confidenciais

Exemplo de .env.local:

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

# Configuração da API
VITE_API_BASE_URL=http://localhost:3000/api
VITE_API_KEY=local-dev-key
# Flags de recursos
VITE_ENABLE_DEBUG=true
VITE_ENABLE_ANALYTICS=false
# Serviços de terceiros
VITE_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

Exemplo de .env.example:

# Configuração da API
VITE_API_BASE_URL=your-api-url-here
VITE_API_KEY=your-api-key-here
# Flags de recursos
VITE_ENABLE_DEBUG=false
VITE_ENABLE_ANALYTICS=true

Lembretes importantes:

• Não envie .env.local ao Git
• Envie .env.example ao Git para orientar a equipe
• Adicione .env*.local ao .gitignore

Tabela rápida de prefixos para variáveis de ambiente

Cada framework exige prefixos diferentes. Esta tabela serve como referência rápida:

Regra fácil de lembrar:

• Se a variável precisa ser acessada no navegador, ela deve ter o prefixo
• Se for usada apenas no servidor, como uma API Key ou senha de banco de dados, não precisa de prefixo

Como investigar variáveis de ambiente que não funcionam?

Já encontrei várias situações em que uma variável estava configurada, mas não funcionava. Este é o checklist que uso para investigar:

Etapas de verificação:

1. Confira o prefixo

   • Um projeto Vite está usando REACT_APP_? O correto é VITE_
   • Uma variável de cliente do Next.js está sem NEXT_PUBLIC_?

2. Confirme que uma nova implantação foi feita

   • Alterações nas variáveis de ambiente só entram em vigor depois de uma nova implantação
   • Você pode enviar uma pequena alteração ao Git ou clicar em “Retry deployment” no Dashboard

3. Confira o ambiente

   • Você alterou Production, mas está acessando um link de Preview?
   • Ou aconteceu o contrário?

4. Consulte o log de build

   • Pesquise o nome da variável no log
   • Confirme se ela foi lida corretamente. Lembre que o valor de uma variável do tipo Secret não aparece

5. Confira a forma de acesso no código

   // ❌ Incorreto (projeto Vite)
   const apiUrl = process.env.VITE_API_URL;
   // ✅ Correto (projeto Vite)
   const apiUrl = import.meta.env.VITE_API_URL;

Técnicas avançadas e boas práticas

Concluir a implantação é só o primeiro passo. Estas técnicas podem deixar o projeto mais profissional.

Vincular um domínio personalizado

Usar um domínio xxx.pages.dev nem sempre parece profissional. Vincular seu próprio domínio é simples.

Etapas:

1. Adicione o domínio no Cloudflare Pages:
   • Acesse o projeto → Custom domains
   • Clique em Set up a custom domain
   • Informe o domínio, como blog.example.com
2. Configure o registro DNS:
   • Se o domínio já estiver no Cloudflare, o registro CNAME será adicionado automaticamente
   • Se estiver em outro provedor, adicione manualmente:

     CNAME  blog  your-project.pages.dev

3. Aguarde a emissão do certificado SSL:
   • O Cloudflare solicitará automaticamente um certificado SSL gratuito
   • Normalmente, ele fica pronto em 5 a 10 minutos

Depois disso, você poderá acessar o projeto pelo seu próprio domínio, com suporte automático a HTTPS.

Preview Deployments (implantações de preview)

Este recurso é especialmente útil para trabalho em equipe. Sempre que você envia código para uma branch que não é a principal ou abre um Pull Request, o CF Pages cria automaticamente um ambiente de preview.

Como usar:

1. Crie uma nova branch:

   git checkout -b feature/new-button

2. Altere o código e faça o push:

   git add .
   git commit -m "Add new button"
   git push origin feature/new-button

3. O CF Pages fará o build e criará automaticamente um link de preview:

   https://abc123.your-project.pages.dev

4. Abra o link no PR e teste o novo recurso

5. Depois do merge na branch principal, o projeto será implantado automaticamente em produção

Vantagens:

• Cada branch de recurso tem um ambiente de preview independente
• Gerentes de produto e designers podem conferir o resultado diretamente
• O ambiente de produção não é afetado

Otimizar o cache de build

Se cada build do projeto demora muito, você pode tentar otimizar o cache.

Adicione uma configuração de cache ao projeto:

O Cloudflare Pages armazena node_modules em cache automaticamente, mas dá para melhorar ainda mais:

1. Use pnpm, que é mais rápido que npm:

   # Adicione .npmrc ao projeto
   echo "package-manager=pnpm" > .npmrc

2. Configure no CF Pages:

   • Altere Build command para pnpm install && pnpm build

3. Remova dependências desnecessárias:

   npm prune

Minha experiência:

Depois de migrar para pnpm, o tempo de build caiu de 5 para 2 minutos. A diferença foi bem perceptível.

Configurar Headers personalizados

Para adicionar Headers HTTP personalizados, como políticas de segurança e controle de cache, crie um arquivo _headers na raiz do projeto:

# Exemplo de arquivo _headers
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: no-referrer-when-downgrade
/static/*
  Cache-Control: public, max-age=31536000, immutable
/api/*
  Cache-Control: no-cache

Salve e faça uma nova implantação. Os Headers entrarão em vigor.

Conclusão

Depois de tudo isso, os pontos principais se resumem a três:

1. Entenda a configuração de build do projeto

• Qual é o Build command? Normalmente, npm run build
• Qual é o diretório de saída? No Vite é dist; no CRA é build; no Next.js, depende do modo
• Quais variáveis de ambiente são necessárias? Observe os prefixos

2. Preste atenção aos problemas mais comuns

• A flag nodejs_compat do Next.js; sem ela, a aplicação retorna erro 500
• Os prefixos das variáveis de ambiente: VITE_ no Vite e NEXT_PUBLIC_ no Next.js
• Erro 404 em rotas SPA; lembre-se de adicionar o arquivo _redirects

3. Aproveite o ambiente de Preview

• Não teste diretamente em produção
• Use uma branch para criar um ambiente de Preview
• Faça o merge na branch principal somente depois dos testes

Sinceramente, o Cloudflare Pages não é tão difícil de usar. A primeira configuração exige algum tempo, mas, depois disso, cada Git Push aciona uma implantação automática e o processo fica muito simples.

O tráfego gratuito ilimitado também é um grande diferencial. Hoje hospedo vários projetos pessoais no CF Pages e não preciso me preocupar com limites de tráfego.

Se você encontrar um problema:

• Consulte a seção de erros comuns deste artigo; boa parte dos problemas que encontrei está documentada ali
• Verifique o log de build. A mensagem de erro normalmente indica onde está o problema
• Embora esteja em inglês, a documentação oficial é bem detalhada: Cloudflare Pages Docs

Próximos passos:

• Implante agora seu primeiro projeto no Cloudflare Pages
• Experimente vincular um domínio personalizado
• Conheça a praticidade das Preview Deployments

Se tiver alguma dúvida, deixe um comentário. Responderei quando puder. Boa implantação!