Skill de Migration OnchainKit

Migrez les apps de @coinbase/onchainkit vers des composants wagmi/viem autonomes sans dépendance à OnchainKit.

Avant de commencer

Créez un fichier mistakes.md à la racine du projet :

# Migration Mistakes & Learnings

Suivez les erreurs, corrections et leçons apprises lors de la migration OnchainKit.

## Errors

## Lessons Learned

Ajoutez chaque erreur, correction et leçon à ce fichier tout au long de la migration. Ce fichier améliore le skill au fil du temps.

Workflow de Migration

Les migrations DOIVENT se faire dans cet ordre. Ne sautez pas d'étapes.

Étape 1 : Détection

Scannez le projet pour comprendre l'utilisation actuelle d'OnchainKit :

1. Recherchez dans tous les fichiers les imports @coinbase/onchainkit
2. Identifiez les composants utilisés :
   • Provider : OnchainKitProvider (toujours présent si vous utilisez OnchainKit)
   • Wallet : Wallet, ConnectWallet, WalletDropdown, WalletModal, Connected
   • Transaction : Transaction, TransactionButton, TransactionStatus
   • Autre : Identity, Avatar, Name, Address, Swap, Checkout, etc.
3. Vérifiez package.json pour les dépendances existantes wagmi, viem, @tanstack/react-query
4. Identifiez l'approche de styling du projet (Tailwind, CSS Modules, styled-components, etc.)
5. Rapportez les découvertes à l'utilisateur avant de continuer

Étape 2 : Migration du Provider (toujours en premier)

Lisez references/provider-migration.md pour les instructions détaillées et le code.

Résumé :

1. Assurez-vous que wagmi, viem et @tanstack/react-query sont installés
2. Créez wagmi-config.ts avec la configuration des chaînes et connecteurs
3. Remplacez OnchainKitProvider par WagmiProvider + QueryClientProvider
4. Supprimez l'import @coinbase/onchainkit/styles.css
5. Supprimez tout import SafeArea ou MiniKit des fichiers de layout

Validation : Exécutez npm run build (ou la commande build du projet). Doit réussir avant de continuer. En cas d'échec, corrigez les erreurs et documentez-les dans mistakes.md.

Étape 3 : Migration du Wallet (après le provider)

Lisez references/wallet-migration.md pour les instructions détaillées et le code.

Résumé :

1. Créez un composant WalletConnect utilisant les hooks wagmi (useAccount, useConnect, useDisconnect)
2. Le composant inclut une modal avec les options de wallet : Base Account, Coinbase Wallet, MetaMask
3. Affiche l'adresse tronquée + bouton de déconnexion quand connecté
4. Remplacez tous les imports et l'utilisation du composant wallet OnchainKit

Validation : Exécutez npm run build. Doit réussir avant de continuer. Documentez toute erreur dans mistakes.md.

Étape 4 : Migration des Transactions (après le wallet)

Lisez references/transaction-migration.md pour les instructions détaillées et le code.

Résumé :

1. Vérifiez la prop chainId sur les composants <Transaction /> existants -- ajoutez les chaînes manquantes à wagmi-config.ts
2. Créez un composant TransactionForm utilisant les hooks wagmi (useWriteContract, useWaitForTransactionReceipt, useSwitchChain)
3. Le composant gère le cycle complet : idle, en attente de confirmation wallet, confirmation on-chain, succès, erreur
4. Remplacez tous les imports de transactions OnchainKit (Transaction, TransactionButton, TransactionStatus, TransactionSponsor, etc.)
5. Mettez à jour le format du tableau calls -- utilisez address, abi, functionName, args avec le typage as const approprié
6. Mappez le callback onStatus aux nouveaux noms de statut du cycle (init, pending, confirmed, success, error)

Validation : Exécutez npm run build. Doit réussir avant de continuer. Documentez toute erreur dans mistakes.md.

Étape 5 : Nettoyage

1. Recherchez tout import @coinbase/onchainkit restant -- il ne devrait y en avoir aucun
2. Optionnellement, supprimez @coinbase/onchainkit des dépendances package.json
3. Exécutez npm run build final pour vérifier que tout fonctionne
4. Mettez à jour mistakes.md avec les leçons finales apprises

Dépannage

La build échoue après la migration du provider

• Dépendances manquantes : Assurez-vous que wagmi, viem, @tanstack/react-query sont installés
• Erreurs de type dans la config wagmi : Vérifiez que le tableau chains a au moins une chaîne et que transports a une entrée correspondante
• "use client" manquant : Le provider et le composant wallet doivent tous deux avoir la directive "use client"

Avertissement MetaMask SDK react-native

• L'avertissement Can't resolve '@react-native-async-storage/async-storage' est inoffensif dans les builds web. Il provient du SDK MetaMask et n'affecte pas la fonctionnalité.

Le wallet ne se connecte pas

• Vérifiez que la config wagmi a les connecteurs corrects configurés
• Vérifiez que WagmiProvider enveloppe l'arborescence des composants avant l'utilisation de tout hook wallet
• Assurez-vous que QueryClientProvider est à l'intérieur de WagmiProvider

Le reçu de transaction reste bloqué en attente

• Symptôme : Le hash de transaction apparaît, la tx se confirme on-chain, mais l'interface reste bloquée sur "Transaction in progress..." pour toujours
• Cause : useWaitForTransactionReceipt n'a pas de RPC pour interroger car la chaîne de la transaction est manquante dans le tableau chains et l'objet transports de la config wagmi
• Solution : (1) Ajoutez la chaîne cible au tableau chains de wagmi-config.ts ET à l'objet transports. (2) Passez toujours chainId à useWaitForTransactionReceipt({ hash, chainId }) pour qu'il interroge la chaîne correcte

La transaction cible la mauvaise chaîne

• TransactionForm change automatiquement de chaîne, mais la chaîne cible doit exister dans le tableau chains de la config wagmi et l'objet transports
• Courant : ajouter baseSepolia pour les transactions testnet (chainId 84532)

Restrictions d'export de page Next.js

• Next.js autorise uniquement des exports nommés spécifiques à partir des fichiers de page. Exporter des tableaux d'appels de contrat ou des constantes ABI à partir d'un fichier de page causera une erreur de build
• Solution : en faire des déclarations const non exportées ou les déplacer vers un module séparé

Erreurs de type ABI après la migration des transactions

• Lors de la définition d'ABIs en ligne, utilisez as const sur le tableau pour une inférence de type appropriée
• Marquez les champs individuels comme type: 'function' as const et stateMutability: 'nonpayable' as const

Configuration wagmi existante détectée

• Si le projet enveloppe déjà avec WagmiProvider, n'en ajoutez PAS un autre
• À la place, mettez à jour simplement la config wagmi existante pour inclure les connecteurs nécessaires
• Le provider OnchainKit détecte et se défère aux providers wagmi existants -- la configuration autonome devrait aussi

Notes Importantes

• Utilisez toujours wagmi et viem directement. Ne jamais importer de @coinbase/onchainkit.
• Le connecteur baseAccount vient de wagmi/connectors, pas d'un package séparé.
• wagmi-config.ts doit inclure chaque chaîne sur laquelle l'app fait des transactions. Si le <Transaction chainId={X} /> OnchainKit original utilisait une chaîne spécifique, cette chaîne doit être dans chains ET transports. Sans cela, useWaitForTransactionReceipt restera bloqué pour toujours.
• Si le projet utilise Tailwind, utilisez les classes Tailwind pour les composants. Sinon, adaptez aux styles inline ou à l'approche de styling existante du projet (p. ex., CSS Modules).
• N'exportez pas les tableaux d'appels de contrat, les constantes ABI ou autres valeurs non-page à partir des fichiers de page Next.js. Utilisez des constantes non exportées ou un module séparé.
• Inspectez le code source OnchainKit dans node_modules/@coinbase/onchainkit/src/ si vous devez comprendre le fonctionnement interne d'un composant spécifique.