Guide complet Cloudflare Pages : déployer React/Vue/Next.js (config + erreurs courantes)

Introduction

Vous avez fini un projet React et vous ouvrez Cloudflare Pages : les champs « Build Command » et « Build Output Directory » vous bloquent. npm run build ou npm build ? build ou dist ? Comment configurer les variables d’environnement ?

Ce guide vous accompagne pour déployer React, Vue et Next.js sur Cloudflare Pages : checklist complète, variables d’environnement et cinq erreurs courantes (dont nodejs_compat pour Next.js).

Pourquoi j’ai choisi Cloudflare Pages ?

Vercel et Netlify existent déjà — pourquoi Pages ?

J’ai longtemps utilisé Vercel. Ce n’est pas mauvais, mais le plan gratuit limite le trafic. Plusieurs petits projets ont dépassé 100 Go/mois ; Vercel a commencé à ralentir.

En comparant les trois plateformes, l’offre gratuite de Cloudflare Pages se démarque :

Le trafic illimité change la donne : plusieurs projets perso sur CF Pages, sans anxiété de quota.

Cas adaptés :

• Blog perso, portfolio
• Projets frontend moyens (SPA, statique)
• Accélération mondiale
• Trafic imprévisible (illimité gratuit)

Moins adaptés :

• Grosses apps Next.js SSR complexes (support Next.js inférieur à Vercel)
• Builds très fréquents (500 builds/mois max)
• Fonctions exclusives Vercel (ex. Edge Middleware)

Préparation avant déploiement

Avant de commencer :

1. Compte Cloudflare
   • Inscription sur cloudflare.com (gratuit)
   • Validation e-mail suffit pour démarrer
2. Dépôt Git
   • Code sur GitHub ou GitLab
   • CF Pages build depuis le dépôt
3. Connaître votre build
   • CRA ou Vite ?
   • Commande de build ? (souvent npm run build)
   • Dossier de sortie ? (CRA : build, Vite : dist)

Prêt ? Passons au déploiement.

Déployer une application React

React est très répandu ; j’ai déployé plusieurs projets React sur CF Pages. Voici une checklist fiable.

Créer rapidement un projet React (optionnel)

# Méthode 1 : Vite (recommandé, build plus rapide)
npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install
# Méthode 2 : Create React App
npx create-react-app my-react-app
cd my-react-app

Je recommande Vite : CRA devient lent sur les gros projets.

Checklist Cloudflare Pages

Dashboard Cloudflare → Pages → « Créer un projet » → « Connecter Git » → choisir le dépôt GitHub.

Configuration :

Notes :

• Vite : preset « None » suffit souvent
• CRA : preset « Create React App » remplit les champs
• Piège fréquent : dist pour Vite, build pour CRA — ne pas inverser

Variables d’environnement

Les variables exposées au client exigent un préfixe spécifique.

Vite :

• Préfixe VITE_
• Ex. : VITE_API_URL, VITE_API_KEY

CRA :

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

• Préfixe REACT_APP_
• Ex. : REACT_APP_API_URL, REACT_APP_API_KEY

Configuration :

1. Dans Cloudflare Pages (recommandé) :
   • Projet → Settings → Environment variables
   • « Add variable »
   • Environnement : Production ou Preview
   • Nom et valeur
2. Dans le code :

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

Local — .env.local :

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

Important :

• Ne pas committer .env.local ; ajouter .env*.local dans .gitignore
• Après modification des variables, redéployer

SPA : corriger le 404 au refresh

Avec React Router, un refresh peut afficher 404 : le serveur cherche un fichier physique au lieu de index.html.

Solution : fichier _redirects dans public :

/* /index.html 200

Une ligne : toutes les routes renvoient index.html avec le statut 200. Redéployez.

Vérifier le déploiement

« Save and Deploy » lance le build. Suivez « Deployments » et les logs.

Succès :

• Log « Success: Deployed to… »
• Lien xxx.pages.dev
• Le site s’affiche

Échec fréquent :

• Mauvais dossier de sortie (Vite → build ou CRA → dist)
• Node trop ancien → variable NODE_VERSION=18
• Échec npm install → vérifier package.json

Déployer une application Vue

Proche de React, avec quelques nuances.

Créer un projet Vue (optionnel)

# Vite (recommandé)
npm create vite@latest my-vue-app -- --template vue
cd my-vue-app
npm install
# Vue CLI
vue create my-vue-app
cd my-vue-app

Checklist Cloudflare Pages

Rappel : Vite et Vue CLI sortent dans dist ; préfixes VITE_ vs VUE_APP_.

Variables d’environnement

Vite + Vue — .env.local :

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

Vue CLI — .env.production :

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

Code :

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

Vue Router

En mode History, configurez la redirection sinon refresh → 404.

Méthode 1 — _redirects dans public (recommandé) :

/* /index.html 200

Méthode 2 — vite.config.js (hors racine) :

// vite.config.js
export default {
  base: '/', // chemin racine
}

Dépannage

Assets statiques 404 : vérifier publicPath / base dans vue.config.js ou vite.config.js :

// vue.config.js (Vue CLI)
module.exports = {
  publicPath: '/',
}

Vite : « Unknown file extension » — souvent Node trop ancien. Ajoutez :

NODE_VERSION=18

puis redéployez.

Déployer Next.js (section importante)

Next.js sur Cloudflare Pages est le plus délicat des trois. La première fois, nodejs_compat m’a bloqué une après-midi.

Pour un gros besoin SSR, Vercel reste souvent plus simple. Pour un site statique ou un SSR léger, CF Pages convient — trafic illimité gratuit inclus.

Spécificités Next.js

1. Pages n’est pas dédié Next.js comme Vercel
2. Deux modes : export statique (simple) ou SSR (adaptateur)
3. SSR : @opennextjs/cloudflare (@cloudflare/next-on-pages est obsolète)

Mode 1 : export statique (recommandé pour débuter)

Sans SSR, API Routes, ISR, etc.

Cas : blog, doc, vitrine, pas de données dynamiques serveur.

Étapes :

1. next.config.js :

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // export statique
  images: {
    unoptimized: true, // pas d'Image Optimization sur CF Pages
  },
}
module.exports = nextConfig

2. Cloudflare Pages :

3. Déployez.

Limites :

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

• ❌ Pas d’API Routes
• ❌ Pas d’ISR
• ❌ Pas de Server Components
• ❌ Pas de SSR sur routes dynamiques

Si cela suffit, l’export statique est la voie la plus simple.

Mode 2 : SSR (adaptateur OpenNext)

Pour API Routes, SSR, routes dynamiques :

npm install @opennextjs/cloudflare

next.config.js :

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    unoptimized: true,
  },
}
module.exports = nextConfig

Cloudflare Pages :

Compatibility Flags (erreur la plus fréquente) :

Sans ce réglage : nodejs_compat is not defined ou 500.

1. Projet → Settings → Functions
2. Compatibility flags
3. Configure Production compatibility flag
4. Ajouter nodejs_compat
5. Compatibility Date : au moins 2024-09-23

Production et Preview doivent avoir le flag.

Edge Runtime :

API Routes ou Server Components → déclaration obligatoire :

// app/api/hello/route.js
export const runtime = 'edge';
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',
};
export default function handler(req) {
  return new Response(JSON.stringify({ message: 'Hello from CF Pages' }), {
    headers: { 'content-type': 'application/json' },
  });
}

Tout fichier exécuté côté serveur doit inclure cette déclaration.

Variables d’environnement Next.js

Client (préfixe obligatoire) :

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

Serveur (sans préfixe) :

DATABASE_URL=postgresql://...
API_SECRET=your-secret-key

Dashboard : Settings → Environment variables → Production / Preview.

// Client
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
// Serveur
const dbUrl = process.env.DATABASE_URL;

Erreurs Next.js courantes

Erreur 1 : nodejs_compat is not defined ou 500

Error: The global scope does not support nodejs_compat

Cause : flag nodejs_compat manquant.

Solution : Settings → Functions → Compatibility flags → ajouter nodejs_compat en Production et Preview → redéployer.

Erreur 2 : build OK mais 404

• Logs OK, xxx.pages.dev en 404, ou seule la home fonctionne

Causes : Edge Runtime absent ou mauvais dossier de sortie.

Solutions :

1. runtime = 'edge' partout où c’est requis
2. Sortie .worker-next (adaptateur) ou out (statique)
3. Export statique : _redirects si besoin

Erreur 3 : FinalizationRegistry is not defined

Cause : Compatibility Date trop ancienne.

Solution : mettre la date à 2024-09-23 ou plus récent → redéployer.

Erreur 4 : build trop long ou échec

• Plus de 10 minutes ou « Build exceeded maximum duration »

Causes : Turbopack (--turbo) ou projet trop lourd.

Solutions :

1. Build command : npx @opennextjs/cloudflare sans --turbo
2. npm prune
3. Envisager l’export statique si possible

Erreur 5 : Image Optimization

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

Solution :

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

Alternatives : Cloudflare Images, CDN tiers (Cloudinary), compression manuelle.

Gestion avancée des variables d’environnement

Trois environnements

Dashboard

Settings → Environment variables — onglets Production et Preview.

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

Recommandations :

1. Production (vraies clés) : type Secret
2. Preview (clés de test) : Plain text possible

Fichiers locaux

my-project/
├── .env.local          # local, non versionné
├── .env.example        # modèle versionné
├── .gitignore

Exemple .env.local :

VITE_API_BASE_URL=http://localhost:3000/api
VITE_API_KEY=local-dev-key
VITE_ENABLE_DEBUG=true
VITE_ENABLE_ANALYTICS=false
VITE_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

.env.example :

VITE_API_BASE_URL=your-api-url-here
VITE_API_KEY=your-api-key-here
VITE_ENABLE_DEBUG=false
VITE_ENABLE_ANALYTICS=true

Ne pas committer .env.local ; versionner .env.example ; .gitignore : .env*.local.

Tableau des préfixes

Astuce : préfixe si lecture navigateur ; pas de préfixe pour secrets serveur uniquement.

Variables inactives : checklist

1. Préfixe — Vite avec REACT_APP_ ? Next client sans NEXT_PUBLIC_ ?
2. Redéploiement après changement
3. Bon environnement (Production vs Preview)
4. Logs — les Secret masquent la valeur
5. Syntaxe code

// ❌ Vite
const apiUrl = process.env.VITE_API_URL;
// ✅ Vite
const apiUrl = import.meta.env.VITE_API_URL;

Astuces et bonnes pratiques

Domaine personnalisé

1. Projet → Custom domains → Set up a custom domain → ex. blog.example.com
2. DNS : CNAME auto si domaine chez Cloudflare, sinon :

CNAME  blog  your-project.pages.dev

3. Certificat SSL gratuit (souvent 5–10 min). HTTPS automatique.

Preview Deployments

Push sur une branche non principale ou PR → environnement de preview automatique.

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

Lien du type https://abc123.your-project.pages.dev — test sans toucher la production.

Cache de build

1. pnpm (souvent plus rapide) :

echo "package-manager=pnpm" > .npmrc

2. Build command : pnpm install && pnpm build
3. npm prune pour alléger les deps

Chez moi : ~5 min → ~2 min après passage à pnpm.

Headers personnalisés

Fichier _headers à la racine :

/*
  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

Redéployez pour appliquer.

Synthèse

Trois idées centrales :

1. Connaître votre build

• Commande ? (souvent npm run build)
• Sortie ? (Vite dist, CRA build, Next selon le mode)
• Variables ? (préfixes)

2. Pièges fréquents

• Next.js : flag nodejs_compat
• Préfixes (VITE_, NEXT_PUBLIC_, etc.)
• SPA : fichier _redirects

3. Preview avant production

• Tester sur une branche
• Fusionner après validation

Une fois configuré, un simple git push suffit. Le trafic illimité gratuit enlève beaucoup de stress sur les petits projets.

En cas de problème : section erreurs ci-dessus, logs de build, documentation Cloudflare Pages.

Prochaines étapes :

• Déployer votre premier projet
• Lier un domaine personnalisé
• Essayer les Preview Deployments

Des questions en commentaire — bon déploiement !