Next.js App aus Localhost in Figma importieren

Was du vorher brauchst

Eine Next.js App, die auf localhost läuft, wird genauso in Figma importiert wie eine bereits veröffentlichte. Die Capture CLI von UnHTML nimmt eine URL entgegen, und eine lokale Adresse ist immer noch eine URL. Führe die Capture CLI gegen die URL deines Dev Servers aus, und sie verhält sich genau wie gegen eine Produktionsdomain. Die zwei Dinge, die sich tatsächlich ändern, sind spezifisch für den Entwicklungsmodus von Next.js, nicht für localhost selbst.

Bevor du anfängst, halte Folgendes bereit:

• Node installiert, und die Capture CLI von UnHTML auf deiner Maschine verfügbar.
• Die Figma Desktop App mit installiertem UnHTML Plugin.
• Deine Next.js App läuft und ist unter einer bekannten Adresse erreichbar, zum Beispiel http://localhost:3000.
• Die genaue Route, die du erfassen willst, nicht nur die Startseite. Falls die Seite Daten clientseitig nachladen muss, wisse, wie sie aussieht, sobald diese Daten angekommen sind.

Mit diesen Voraussetzungen läuft der Import in sechs Schritten ab: URL bestätigen, Dev oder Production Build wählen, Dev Indicator ausblenden, Hydration abwarten, Capture ausführen, dann den Import Report lesen.

Schritt für Schritt: einen Next.js Dev Server erfassen

Schritt 1: Bestätige, dass die App unter ihrer lokalen URL erreichbar ist. Öffne die genaue Route zuerst in deinem Browser und prüfe, ob sie so rendert wie erwartet. Die Capture CLI holt genau das, was diese URL in dem Moment zurückgibt, in dem du sie ausführst. Ein halb gestarteter Dev Server oder eine Route mit 404 wird also exakt so erfasst, defekt.

Schritt 2: Entscheide zwischen Dev Build und Production Build. next dev ist schneller zum Iterieren, weil du CSS anpassen und neu laden kannst. next build && next start entfernt das reine Dev Scaffolding, bevor die Seite überhaupt den Capture Schritt erreicht, was ein saubereres Ergebnis liefert. Dev Modus ist für einen einmaligen Import in Ordnung, sobald du Schritt 3 erledigt hast. Für eine Seite, die du mehrmals neu erfasst, während du das Layout verfeinerst, erspart dir der Production Build, diesen Schritt jedes Mal zu wiederholen.

Schritt 3: Blende den Dev Mode Route Indicator von Next.js aus. In der Entwicklung fügt Next.js einen Bildschirmindikator ein, der Kontext über die aktuelle Route zeigt, standardmäßig unten links (bottom-left) positioniert. UnHTML erfasst, was tatsächlich im DOM steht, also landet dieser Indikator als eigene Ebene, wenn du ihn nicht vorher entfernst. Konfiguriere ihn in next.config.ts:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  devIndicators: false,
}

export default nextConfig

Möchtest du den Indikator für dein eigenes Debugging behalten? Verschiebe ihn mit devIndicators: { position: 'top-right' } aus dem Erfassungsbereich. Next.js' eigene devIndicators Referenz zeigt, dass die Option position mit Next.js 15.2.0 kam, und dass die älteren Optionen appIsrStatus, buildActivity und buildActivityPosition, die sie ersetzte, in Next.js 16.0.0 vollständig entfernt wurden. Die Konfigurationsschlüssel können also abweichen, wenn du eine ältere Version nutzt. Beide Einstellungen lassen Next.js weiterhin echte Compile und Runtime Fehler anzeigen. Du blendest nur das kosmetische Badge aus.

Schritt 4: Lass die Seite vollständig hydrieren, bevor du sie erfasst. Ein Dev Server lädt lokale Daten oft langsamer als eine Production API, besonders wenn sie aus einem Mock oder einer lokalen Datenbank kommen. Zeigt eine Client Komponente noch ein Lade Skeleton oder einen Spinner, wenn die CLI die Seite abruft, landet genau dieses Skeleton in Figma, nicht das fertige Layout. Beobachte in deinem Browser, bis sich die Seite stabilisiert hat, bevor du weitermachst.

Schritt 5: Führe die Capture CLI gegen die localhost URL aus.

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

Das holt die Seite ohne CORS Limits und macht einen Full Page Scroll, sodass Inhalte unterhalb des sichtbaren Bereichs ebenfalls erfasst werden. Die Ausgabe ist eine scene.json Datei.

Schritt 6: Ziehe scene.json in das UnHTML Plugin in Figma, und lies dann den Import Report. Das Plugin rendert die Erfassung in einem echten Browser Kontext, misst jeden Knoten und baut native Frames, Text, Bilder, Vektoren und Auto Layout aus dem eigenen CSS der Seite. Der Report zeigt dir, was sich dabei verändert hat. Jede Schriftart, die auf deiner Maschine nicht installiert ist, wird ersetzt, standardmäßig durch Inter, und jeder Tausch wird protokolliert. Jeder Abschnitt, der für ein saubereres Auto Layout Mapping zu komplex ist, fällt auf absolute Positionierung zurück. Das ist kein pixelgenauer Klon, und der Report existiert genau deshalb, damit du siehst, wo es abgewichen ist.

Warum localhost für die Capture CLI nur eine weitere URL ist

Der Grund, warum das ohne Sonderbehandlung funktioniert, liegt daran, wie die Same Origin Policy Anfragen behandelt. Eine Anfrage braucht nur dann CORS Header, wenn sie eine Origin Grenze überschreitet: ein anderes Protokoll, eine andere Domain oder ein anderer Port als der, von dem sie kam. Eine Seite, die ihre eigenen Ressourcen von ihrer eigenen Origin lädt, löst diese Einschränkung nie aus, egal ob diese Origin https://example.com oder http://localhost:3000 ist. Die Capture CLI holt die Seite selbst ab, aus ihrer Sicht sind ein lokaler Dev Server und eine Produktionsdomain also nur eine Origin, die sie anfragt. Nichts weiter.

Das erklärt auch, warum das Importieren einer React oder Vue Site in Figma und das Importieren einer Next.js App auf localhost derselbe Workflow mit demselben Werkzeug sind. Next.js ist ein React Framework, und die CLI unterscheidet nicht, welches Framework das abgerufene HTML gerendert hat. Was bei localhost wirklich anders ist: es gibt keinen öffentlichen DNS Eintrag und kein CDN davor, also muss die CLI auf einer Maschine laufen, die die Adresse deines Dev Servers tatsächlich erreichen kann. Führe sie auf derselben Maschine wie den Dev Server aus, oder im selben Netzwerk, und das Problem verschwindet.

Was die Capture CLI nicht sehen kann

Die Capture CLI stellt eine nicht authentifizierte Anfrage an die URL, die du angibst. Liegt deine Route hinter einem lokalen Login, sei es NextAuth, ein Middleware Redirect oder deine eigene Session Prüfung, sieht die CLI das, was ein nicht authentifizierter Besucher sieht: einen Login Bildschirm, oder einen Redirect. Nicht deine echte Seite.

Die Lösung ist, ein DOM zu erfassen, das bereits im gewünschten Zustand ist, statt die CLI zu bitten, diesen Zustand selbst herzustellen. Melde dich in deinem eigenen Browser an, und nutze dann den Export von Self Contained HTML von dieser bereits gerenderten, bereits authentifizierten Seite, oder speichere sie als Safari Webarchive. Beide sind dateibasierte Eingaben, die das UnHTML Plugin direkt akzeptiert. Kein CLI Abruf nötig.

Dieselbe Einschränkung gilt für jeden rein clientseitigen Datenzustand. Erfasst du einen Spinner, bekommst du einen Spinner. Zeigt deine lokale App einen, während sie auf eine langsame lokale API wartet, und du erfasst genau in diesem Moment, wird dieser Spinner zur Ebene in Figma, nicht der geladene Inhalt. Figma Plugins bauen native Scene Nodes programmatisch auf, statt ein flaches Bild einzusetzen, also baut das UnHTML Plugin echte Nodes aus dem, was die Erfassung aufgezeichnet hat, nicht aus dem, was die Seite eigentlich zeigen sollte. Die Treue ist durch den DOM Zustand zum Erfassungszeitpunkt begrenzt, nicht durch irgendetwas, das das Plugin danach erschließen könnte.

Fazit

Localhost ist für UnHTML kein Sonderfall. Die Capture CLI behandelt eine Dev Server Adresse genau wie jede andere URL, weil dieselben Origin Regeln, die CORS für die eigenen Ressourcen einer Seite irrelevant machen, unabhängig davon gelten, ob diese Seite von localhost oder von einer Produktionsdomain ausgeliefert wird. Die Anpassungen, die sich lohnen, sind spezifisch für den Entwicklungsmodus von Next.js: blende den Bildschirmindikator vor dem Erfassen aus, und warte, bis die Seite vollständig hydriert ist, damit du keinen Ladezustand importierst. Sobald der Import angekommen ist, ist das Umwandeln der wiederholten Abschnitte in wiederverwendbare Komponenten der nächste natürliche Schritt, behandelt im Artikel über den Aufbau von Figma Komponenten aus einem Import.

Häufig gestellte Fragen

Kann UnHTML eine Next.js App importieren, die nur auf localhost läuft?

Ja. Die Capture CLI nimmt jede URL entgegen, einschließlich einer localhost Adresse, und holt sie ohne CORS Limits und mit Full Page Scroll ab, wobei sie eine scene.json erzeugt, die du in das Figma Plugin ziehst. Für den Importpfad spielt es keine Rolle, ob die URL im öffentlichen Internet oder auf 127.0.0.1 aufgelöst wird. Sie muss nur von der Maschine aus erreichbar sein, auf der die CLI läuft.

Muss ich meine Next.js App deployen, bevor ich sie in Figma importiere?

Nein. Deployment ist eine Möglichkeit, eine stabile URL zu bekommen, aber ein laufender Dev Server (next dev) auf localhost lässt sich genauso erfassen. Die wichtigere Entscheidung ist Dev Build gegen Production Build: next build && next start entfernt den Bildschirm Dev Indicator und alle reinen Dev Warnungen aus dem DOM, was eine sauberere Erfassung ergibt, aber next dev funktioniert auch gut, sobald du den Indikator ausgeblendet hast.

Warum erscheint der Dev Mode Indikator von Next.js als Ebene in Figma?

UnHTML erfasst, was tatsächlich im DOM der Seite zum Zeitpunkt der Erfassung gerendert wird, und der Bildschirm Route Indikator, den Next.js in der Entwicklung einfügt, ist Teil dieses DOM. Setze devIndicators: false in next.config.ts, bevor du erfasst, oder verschiebe ihn mit der position Option aus dem Bildausschnitt, und er erscheint nicht im Import.

Sieht die Capture CLI Inhalte hinter einem Login in meiner lokalen App?

Nicht standardmäßig. Die CLI holt die URL frisch ab, sieht also nur, was eine nicht authentifizierte Anfrage rendert. Für eine Route, die eine Session braucht, melde dich zuerst in deinem eigenen Browser an und nutze einen Self Contained HTML Export oder ein Safari Webarchive dieser bereits authentifizierten Seite, statt die CLI direkt auf die URL zeigen zu lassen.

Sollte ich eine Next.js Seite im Dev Modus erfassen oder sie vorher für die Produktion bauen?

Production ist sauberer, wenn du dir die Build Zeit leisten kannst: kein Dev Indicator, kein Fast Refresh Scaffolding, und dieselben Code Pfade, die deine Besucher sehen. Dev Modus ist schneller zum Iterieren und für die meiste Layout und Abstandsarbeit in Ordnung, solange du den Indikator ausblendest und wartest, bis die Seite vollständig hydriert ist, bevor du sie erfasst.