cloudflare/migrate-to-vinext

Que fait migrate-to-vinext ?

Migre les projets Next.js vers vinext (une réimplémentation de Next.js basée sur Vite). Activez cette compétence lorsqu'on vous demande de migrer, convertir ou passer de Next.js à vinext. Elle gère l'analyse de compatibilité, le remplacement des packages, la génération de configuration Vite, la conversion ESM et la configuration de déploiement (Cloudflare Workers nativement, autres plateformes via Nitro).

Comment l'utiliser

Demandez à votre agent de migration de réaliser les étapes suivantes :

1. Analyser la compatibilité : Scannez votre projet Next.js existant pour identifier les fichiers, dépendances et configurations incompatibles.
2. Remplacer les packages : Remplacez next, next/dynamic, next/link et autres packages spécifiques à Next.js par leurs équivalents vinext.
3. Générer la configuration Vite : Créez un fichier vite.config.ts (ou vite.config.js) avec les paramètres appropriés, en conservant si nécessaire la configuration existante.
4. Convertir les modules CJS en ESM : Transformez les fichiers CommonJS en modules ES, en ajustant les imports et exports.
5. Configurer le déploiement :
   • Pour Cloudflare Workers : utilisez l'export natif de vinext.
   • Pour d'autres plateformes (Netlify, Vercel, AWS Lambda, etc.) : utilisez Nitro comme adaptateur de déploiement.

Commandes CLI

# Analyse de compatibilité
npx @cloudflare/vinext-migration scan ./mon-projet-next

# Migration automatique
npx @cloudflare/vinext-migration migrate ./mon-projet-next

# Génération de la configuration Vite
npx @cloudflare/vinext-migration generate-config

# Conversion des modules CJS en ESM
npx @cloudflare/vinext-migration convert-esm ./mon-projet-next

# Configuration du déploiement pour Cloudflare Workers
npx @cloudflare/vinext-migration setup-deploy --platform cloudflare

# Configuration du déploiement pour d'autres plateformes via Nitro
npx @cloudflare/vinext-migration setup-deploy --platform nitro

Exemple de migration

Avant (Next.js)

// pages/index.js
import Link from 'next/link';
import { useRouter } from 'next/router';

export default function Home() {
  const router = useRouter();
  return (
    <div>
      <h1>Bienvenue</h1>
      <Link href="/about">À propos</Link>
    </div>
  );
}

Après (vinext)

// pages/index.jsx
import { Link, useRouter } from 'vinext/router';

export default function Home() {
  const router = useRouter();
  return (
    <div>
      <h1>Bienvenue</h1>
      <Link href="/about">À propos</Link>
    </div>
  );
}

Configuration avancée

Variables d'environnement

• VINEXT_MIGRATION_DIR : Répertoire de sortie pour les fichiers migrés (défaut : ./vinest-migrated)
• VINEXT_KEEP_ORIGINAL : Conserver les fichiers Next.js d'origine (défaut : false)
• VINEXT_ESM_EXTENSIONS : Extensions de fichiers à convertir en ESM (défaut : .js,.jsx,.ts,.tsx)
• VINEXT_DEPLOY_PLATFORM : Plateforme de déploiement cible (cloudflare ou nitro)

Options de ligne de commande

Option	Description	Valeur par défaut
--dry-run	Simule la migration sans écrire les fichiers	false
--verbose	Affiche les détails de la migration	false
--force	Ignorer les avertissements de compatibilité	false
--platform <type>	Plateforme de déploiement cible	cloudflare

Remarques importantes

• Certaines fonctionnalités de Next.js (comme ISR) peuvent ne pas être supportées par vinext. Consultez la documentation officielle pour la liste complète des fonctionnalités compatibles.
• La migration est irréversible si VINEXT_KEEP_ORIGINAL est désactivé. Assurez-vous de sauvegarder votre projet avant de lancer la migration.
• Pour les déploiements sur Cloudflare Workers, aucune configuration supplémentaire n'est nécessaire : vinext embarque un adaptateur natif.
• Pour les autres plateformes, Nitro fournit des adaptateurs pour Netlify, Vercel, AWS Lambda, etc.

Dépannage

Erreur : "Package 'next' introuvable"

Assurez-vous que le package next est installé dans le projet source avant de lancer la migration.

Erreur : "Conversion ESM impossible"

Vérifiez que les fichiers à convertir utilisent une syntaxe CommonJS (require/module.exports). Les fichiers déjà au format ESM sont ignorés.

Problème de déploiement

Consultez la documentation de l'adaptateur choisi (Cloudflare Workers ou Nitro) pour les configurations spécifiques de déploiement.