La solution ultime : Migrer Next.js 15 de Cloudflare Pages vers Workers avec OpenNext
Si vous avez construit des applications Next.js 15 et que vous les avez déployées sur Cloudflare Pages en utilisant @cloudflare/next-on-pages, vous vous êtes probablement heurté à un mur.
La redoutée erreur "Invalid prerender config", le rendu incohérent entre les routes statiques et dynamiques, et les conflits de configuration du runtime edge ont été des maux de tête majeurs pour la communauté. Après des heures passées à déboguer ces problèmes précis sur mon site portfolio, j'ai enfin trouvé la solution à toute épreuve : Migrer de Cloudflare Pages à Cloudflare Workers en utilisant OpenNext.
Dans ce guide, je vais vous montrer exactement pourquoi Next.js sur Pages échoue et comment migrer proprement votre architecture vers Cloudflare Workers pour un déploiement parfait et robuste.
Le problème : Les limites de Next-on-Pages
Cloudflare Pages a été conçu à l'origine pour des sites purement statiques. Bien qu'il ait évolué pour prendre en charge le Server-Side Rendering (SSR) et les Edge Functions via @cloudflare/next-on-pages, l'intégration avec l'App Router de Next.js 15 reste fragile.
Lorsque vous mélangez des routes statiques SSG (comme des articles de blog) avec des routes dynamiques edge (comme des endpoints API ou des requêtes de base de données), le processus de compilation s'étouffe souvent :
Error: Invalid prerender config for /app/[locale]/about
The following routes were not configured to run with the Edge Runtime...
Le problème sous-jacent est un décalage entre la manière dont la sortie de compilation de Vercel s'attend à ce que les fonctions soient structurées et la façon dont next-on-pages les interprète pour l'environnement Pages.
La solution : OpenNext et Cloudflare Workers
Au lieu de vous battre avec le système de compilation de Pages, l'approche moderne consiste à utiliser OpenNext (@opennextjs/cloudflare) et à déployer directement sur Cloudflare Workers.
Les Workers offrent un véritable environnement d'exécution serverless qui s'aligne parfaitement avec les exigences SSR et les routes API de Next.js, tandis que Cloudflare Assets gère les fichiers statiques.
Voici le chemin de migration étape par étape.
Étape 1 : Installer les dépendances
Supprimez next-on-pages et installez OpenNext pour Cloudflare :
npm uninstall @cloudflare/next-on-pages
npm install -D @opennextjs/cloudflare
Étape 2 : Configurer OpenNext
Créez un fichier open-next.config.ts à la racine de votre projet. Cela indique à OpenNext comment adapter votre compilation Next.js pour Cloudflare :
import type { OpenNextConfig } from 'open-next/types/open-next.js';
export default {
default: {
override: {
wrapper: 'cloudflare-node',
converter: 'edge',
incrementalCache: 'dummy',
tagCache: 'dummy',
queue: 'dummy',
},
},
middleware: {
external: true,
override: {
wrapper: 'cloudflare-edge',
converter: 'edge',
proxyExternalRequest: 'fetch',
},
},
} as OpenNextConfig;
Étape 3 : Configurer Wrangler pour les Workers
Vous avez besoin d'un wrangler.jsonc (ou wrangler.toml) pour définir le déploiement de votre Worker. Remarquez comment nous pointons l'entrée principale vers le worker généré par OpenNext, et lions les ressources statiques.
{
"main": ".open-next/worker.js",
"name": "your-project-name",
"compatibility_date": "2026-06-15",
"compatibility_flags": [
"nodejs_compat"
],
"assets": {
"directory": ".open-next/assets",
"binding": "ASSETS"
}
}
Étape 4 : Mettre à jour les scripts de compilation
Mettez à jour votre package.json pour compiler d'abord avec Next.js, puis traiter avec OpenNext :
"scripts": {
"build": "next build && opennextjs-cloudflare",
"preview": "npm run build && wrangler dev",
"deploy": "npm run build && wrangler deploy"
}
Étape 5 : Nettoyer les configurations Edge
Avec OpenNext, vous n'avez plus besoin d'imposer strictement export const runtime = 'edge' en haut de chaque fichier dynamique juste pour apaiser le système de compilation. L'enveloppe cloudflare-node d'OpenNext gère intelligemment les API Node.js et Edge, simplifiant considérablement votre base de code.
Et à propos de Cloudflare R2 ?
Lors de cette migration, vous pourriez vous demander si vous devez provisionner un bucket Cloudflare R2.
La réponse courte : Non, pas immédiatement.
Vos ressources statiques Next.js (images, CSS, chunks JS) sont parfaitement servies par la liaison Cloudflare Assets définie dans votre wrangler.jsonc.
Cependant, si votre application évolue pour gérer des médias téléchargés par les utilisateurs, de grandes vidéos ou des ensembles de données massifs, R2 s'intègre parfaitement dans cette architecture Worker. Il vous suffit de lier le bucket R2 dans votre wrangler.jsonc et d'y accéder via env.MY_BUCKET dans vos Server Actions ou routes API.
Le résultat
En migrant vers Cloudflare Workers avec OpenNext, vous obtenez :
- Zéro erreur de compilation : Fini de s'arracher les cheveux sur les configurations de prérendu.
- Une localisation sans faille : Le routage internationalisé (
/[locale]/) fonctionne immédiatement. - Compatibilité Node.js : Le drapeau
nodejs_compatpermet une prise en charge plus large des packages npm.
Cloudflare Pages est fantastique pour les sites statiques simples, mais pour les applications Next.js 15 ambitieuses, OpenNext sur Cloudflare Workers est la voie définitive à suivre.