Comment importer une app Next.js en localhost dans Figma

Ce qu'il vous faut avant de commencer

Une app Next.js qui tourne en localhost s'importe dans Figma de la même façon qu'une app déjà déployée. Le CLI de capture d'UnHTML prend une URL, et une adresse locale reste une URL. Lancez le CLI de capture sur l'URL de votre serveur de dev, et il se comporte exactement comme contre un domaine en production. Les deux choses qui changent réellement sont propres au mode développement de Next.js, pas à localhost lui-même.

Avant de commencer, ayez ceci sous la main:

• Node installé, et le CLI de capture d'UnHTML disponible sur votre machine.
• L'app de bureau Figma avec le plugin UnHTML installé.
• Votre app Next.js lancée et accessible à une adresse connue, par exemple http://localhost:3000.
• La route exacte que vous voulez capturer, pas seulement la page d'accueil. Si la page doit charger des données côté client, sachez à quoi elle ressemble une fois ces données arrivées.

Une fois cela en place, l'import se résume à six étapes: confirmer l'URL, choisir entre build de dev ou de production, masquer l'indicateur de mode dev, attendre l'hydratation, lancer la capture, puis lire le rapport d'import.

Étape par étape: capturer un serveur de dev Next.js

Étape 1: confirmez que l'app est accessible à son URL locale. Ouvrez d'abord la route exacte dans votre navigateur et vérifiez qu'elle se rend comme attendu. Le CLI de capture récupère ce que cette URL renvoie au moment où vous l'exécutez, donc un serveur de dev à moitié démarré ou une route en 404 sera capturé exactement ainsi, cassé.

Étape 2: choisissez entre build de dev et build de production. next dev est plus rapide à itérer, puisque vous pouvez ajuster le CSS et recharger. next build && next start retire l'échafaudage propre au mode dev avant même que la page n'atteigne l'étape de capture, ce qui donne un résultat plus propre. Le mode dev convient pour un import ponctuel, une fois l'étape 3 réglée. Pour une page que vous recapturerez plusieurs fois en peaufinant la mise en page, le build de production vous évite de refaire cette étape chaque fois.

Étape 3: masquez l'indicateur de route du mode dev de Next.js. En développement, Next.js injecte un indicateur à l'écran qui donne du contexte sur la route actuelle, positionné par défaut en bottom-left. UnHTML capture ce qui est réellement dans le DOM, donc cet indicateur arrive comme un calque si vous ne le retirez pas d'abord. Configurez-le dans next.config.ts:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  devIndicators: false,
}

export default nextConfig

Vous préférez garder l'indicateur pour votre propre débogage? Déplacez-le hors de la zone de capture avec devIndicators: { position: 'top-right' }. La référence devIndicators de Next.js montre que l'option position est arrivée dans Next.js 15.2.0, et que les anciennes options appIsrStatus, buildActivity et buildActivityPosition qu'elle a remplacées ont été entièrement retirées dans Next.js 16.0.0, donc la clé de config peut différer si vous êtes sur une version plus ancienne. Les deux réglages laissent toujours Next.js afficher les vraies erreurs de compilation et d'exécution. Vous ne masquez que le badge cosmétique.

Étape 4: laissez la page s'hydrater entièrement avant de la capturer. Un serveur de dev charge souvent les données locales plus lentement qu'une API de production, surtout depuis un mock ou une base de données locale. Si un composant client affiche encore un squelette de chargement ou un spinner quand le CLI récupère la page, c'est ce squelette qui atterrit dans Figma, pas la mise en page finale. Observez la page se stabiliser dans votre navigateur avant de continuer.

Étape 5: lancez le CLI de capture sur l'URL localhost.

node capture/cli/capture.js http://localhost:3000/your-route --out scene.json

Cela récupère la page sans limite CORS et fait un scroll de page complète, donc le contenu sous la ligne de flottaison est aussi capturé avec ce qui est visible au chargement. La sortie est un fichier scene.json.

Étape 6: glissez scene.json dans le plugin UnHTML dans Figma, puis lisez le rapport d'import. Le plugin rend la capture dans un vrai contexte de navigateur, mesure chaque nœud, et construit des frames, du texte, des images, des vecteurs et de l'auto layout natifs à partir du CSS propre de la page. Le rapport vous dit ce qui a changé en chemin. Toute police non installée sur votre machine est remplacée, par défaut par Inter, et chaque substitution est consignée. Toute section trop complexe pour un mapping d'auto layout propre retombe sur un positionnement absolu. Ce n'est pas un clone exact au pixel, et le rapport existe justement pour que vous voyiez où ça a divergé.

Pourquoi localhost n'est qu'une URL de plus pour le CLI de capture

La raison pour laquelle cela fonctionne sans traitement particulier tient à la façon dont la politique de même origine traite les requêtes. Une requête n'a besoin d'en-têtes CORS que lorsqu'elle traverse une frontière d'origine: un protocole, un domaine ou un port différent de celui d'où elle vient. Une page qui récupère ses propres ressources depuis sa propre origine ne déclenche jamais cette restriction, que cette origine soit https://example.com ou http://localhost:3000. Le CLI de capture récupère la page lui-même, donc de son point de vue un serveur de dev local et un domaine de production sont juste une origine qu'il interroge. Rien de plus.

C'est aussi pourquoi importer un site React ou Vue dans Figma et importer une app Next.js en localhost finissent par être le même flux de travail avec le même outil. Next.js est un framework React, et le CLI ne se soucie pas de quel framework a rendu le HTML qu'il a récupéré. Ce qui diffère vraiment avec localhost: il n'y a pas d'entrée DNS publique ni de CDN devant, donc le CLI doit s'exécuter sur une machine qui peut réellement atteindre l'adresse de votre serveur de dev. Lancez-le sur la même machine que le serveur de dev, ou sur le même réseau, et cela cesse d'être un problème.

Ce que le CLI de capture ne peut pas voir

Le CLI de capture fait une requête non authentifiée vers l'URL que vous lui donnez. Si votre route est derrière une connexion locale, que ce soit NextAuth, une redirection de middleware ou votre propre vérification de session, le CLI voit ce qu'un visiteur non authentifié voit: un écran de connexion, ou une redirection. Pas votre vraie page.

La solution consiste à capturer un DOM déjà dans l'état voulu, plutôt que de demander au CLI de reproduire cet état lui-même. Connectez-vous dans votre propre navigateur, puis utilisez l'export HTML autonome depuis cette page déjà rendue, déjà authentifiée, ou enregistrez-la comme webarchive Safari. Les deux sont des entrées basées sur des fichiers que le plugin UnHTML accepte directement. Aucune requête CLI nécessaire.

La même limitation s'applique à tout état de données purement côté client. Capturez un spinner, et c'est un spinner que vous obtenez. Si votre app locale en affiche un en attendant une API locale lente, et que vous capturez à ce moment précis, ce spinner devient le calque dans Figma, pas le contenu chargé. Les plugins Figma construisent des nœuds de scène natifs de façon programmatique plutôt que de placer une image aplatie, donc le plugin UnHTML construit de vrais nœuds à partir de ce que la capture a enregistré, pas de ce que vous vouliez que la page finisse par montrer. La fidélité est limitée par l'état du DOM au moment de la capture, pas par ce que le plugin pourrait déduire après coup.

Conclusion

Localhost n'est pas un cas particulier pour UnHTML. Le CLI de capture traite une adresse de serveur de dev exactement comme n'importe quelle autre URL, car les mêmes règles d'origine qui rendent CORS sans importance pour les propres ressources d'une page s'appliquent, que cette page soit servie depuis localhost ou depuis un domaine de production. Les ajustements qui valent la peine sont propres au mode développement de Next.js: masquez l'indicateur de dev à l'écran avant de capturer, et attendez que la page finisse de s'hydrater pour ne pas importer un état de chargement. Une fois l'import arrivé, transformer les sections répétées en composants réutilisables est l'étape naturelle suivante, traitée dans l'article sur la construction de composants Figma à partir d'un import.

Questions fréquentes

UnHTML peut-il importer une app Next.js qui tourne seulement en localhost?

Oui. Le CLI de capture prend n'importe quelle URL, y compris une adresse localhost, et la récupère sans limite CORS et avec un scroll de page complète, en écrivant un scene.json que vous glissez dans le plugin Figma. Rien dans le chemin d'import ne se soucie que l'URL se résolve sur l'internet public ou sur 127.0.0.1. Elle doit juste être accessible depuis la machine qui exécute le CLI.

Dois-je déployer mon app Next.js avant de l'importer dans Figma?

Non. Déployer est une façon d'obtenir une URL stable, mais un serveur de dev en cours d'exécution (next dev) en localhost est tout aussi capturable. La décision la plus importante est build de dev contre build de production: next build && next start retire l'indicateur de dev à l'écran et tous les avertissements propres au mode dev du DOM, pour une capture plus propre, mais next dev fonctionne tout aussi bien une fois l'indicateur masqué.

Pourquoi l'indicateur du mode dev de Next.js apparaît-il comme un calque dans Figma?

UnHTML capture ce qui est réellement rendu dans le DOM de la page au moment de la capture, et l'indicateur de route à l'écran que Next.js injecte en développement fait partie de ce DOM. Réglez devIndicators: false dans next.config.ts avant de capturer, ou déplacez-le hors cadre avec l'option position, et il n'apparaîtra pas dans l'import.

Le CLI de capture voit-il le contenu derrière une connexion sur mon app locale?

Pas par défaut. Le CLI récupère l'URL à neuf, donc il ne voit que ce qu'une requête non authentifiée rend. Pour une route qui nécessite une session, connectez-vous d'abord dans votre propre navigateur et utilisez un export HTML autonome ou un webarchive Safari de cette page déjà authentifiée, plutôt que de pointer le CLI directement sur l'URL.

Dois-je capturer une page Next.js en mode dev ou la construire pour la production d'abord?

La production est plus propre quand vous pouvez vous permettre le temps de build: pas d'indicateur de dev, pas d'échafaudage Fast Refresh, et les mêmes chemins de code que voient vos visiteurs. Le mode dev est plus rapide à itérer et convient pour la plupart du travail de mise en page et d'espacement, tant que vous masquez l'indicateur et attendez que la page s'hydrate entièrement avant de la capturer.