Cómo Importar una App de Next.js en Localhost a Figma

Lo que necesitas antes de empezar

Una app de Next.js que corre en localhost se importa a Figma igual que una ya desplegada. El CLI de captura de UnHTML recibe una URL, y una dirección local sigue siendo una URL. Ejecuta el CLI de captura contra la URL de tu servidor de desarrollo y se comporta exactamente igual que contra un dominio en producción. Las dos cosas que realmente cambian son específicas del modo de desarrollo de Next.js, no de localhost en sí.

Antes de empezar, ten listo esto:

• Node instalado, y el CLI de captura de UnHTML disponible en tu máquina.
• La app de escritorio de Figma con el plugin de UnHTML instalado.
• Tu app de Next.js corriendo y accesible en una dirección conocida, por ejemplo http://localhost:3000.
• La ruta exacta que quieres capturar, no solo la página de inicio. Si la página necesita cargar datos del lado del cliente, sabe cómo se ve una vez que esos datos ya llegaron.

Con eso listo, la importación se reduce a seis pasos: confirmar la URL, elegir entre build de desarrollo o de producción, ocultar el indicador de modo desarrollo, esperar la hidratación, ejecutar la captura y luego leer el informe de importación.

Paso a paso: capturar un servidor de desarrollo de Next.js

Paso 1: Confirma que la app es accesible en su URL local. Abre la ruta exacta en tu navegador primero y comprueba que se renderiza como esperas. El CLI de captura obtiene lo que esa URL devuelva en el momento en que lo ejecutas, así que un servidor de desarrollo a medio iniciar o una ruta con error 404 se captura exactamente así, rota.

Paso 2: Decide entre build de desarrollo o de producción. next dev es más rápido para iterar, ya que puedes ajustar CSS y recargar. next build && next start elimina el andamiaje propio del modo desarrollo antes de que la página llegue siquiera al paso de captura, lo que da un resultado más limpio. El modo desarrollo está bien para una importación puntual, una vez que resuelves el Paso 3. Para una página que vas a recapturar varias veces mientras ajustas el diseño, el build de producción te ahorra repetir ese paso cada vez.

Paso 3: Oculta el indicador de ruta del modo desarrollo de Next.js. En desarrollo, Next.js inyecta un indicador en pantalla que muestra contexto sobre la ruta actual, ubicado por defecto en bottom-left. UnHTML captura lo que realmente está en el DOM, así que ese indicador llega como una capa a menos que lo elimines primero. Configúralo en next.config.ts:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  devIndicators: false,
}

export default nextConfig

¿Prefieres conservar el indicador para tu propio trabajo de depuración? Muévelo fuera del área de captura con devIndicators: { position: 'top-right' }. La propia referencia de devIndicators de Next.js muestra que la opción position llegó en Next.js 15.2.0, y que las opciones anteriores appIsrStatus, buildActivity y buildActivityPosition que reemplazó se eliminaron por completo en Next.js 16.0.0, así que la clave de configuración puede variar si usas una versión anterior. Cualquiera de las dos configuraciones sigue dejando que Next.js muestre errores reales de compilación y de ejecución. Solo estás ocultando la insignia cosmética.

Paso 4: Deja que la página hidrate por completo antes de capturarla. Un servidor de desarrollo suele cargar datos locales más lento que una API de producción, sobre todo si viene de un mock o de una base de datos local. Si un componente de cliente todavía muestra un esqueleto de carga o un spinner cuando el CLI obtiene la página, ese esqueleto es lo que llega a Figma, no el diseño terminado. Observa que la página se estabilice en tu navegador antes de seguir.

Paso 5: Ejecuta el CLI de captura contra la URL de localhost.

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

Esto obtiene la página sin límites de CORS y hace un scroll de página completa, de modo que el contenido debajo del pliegue también se captura junto con lo visible al cargar. La salida es un archivo scene.json.

Paso 6: Arrastra scene.json al plugin de UnHTML en Figma, y luego lee el informe de importación. El plugin renderiza la captura en un contexto real de navegador, mide cada nodo y construye frames, texto, imágenes, vectores y auto layout nativos a partir del propio CSS de la página. El informe te dice qué cambió en el camino. Cualquier fuente que no esté instalada en tu máquina se sustituye, por defecto con Inter, y cada sustitución queda registrada. Cualquier sección demasiado compleja para un mapeo limpio de auto layout cae de vuelta a posicionamiento absoluto. Esto no es un clon pixel perfecto, y el informe existe precisamente para que veas en qué puntos se desvió.

Por qué localhost es solo otra URL más para el CLI de captura

La razón por la que esto funciona sin manejo especial se reduce a cómo la política de mismo origen trata las solicitudes. Una solicitud solo necesita cabeceras CORS cuando cruza un límite de origen: un protocolo, dominio o puerto distinto al de origen. Una página que obtiene sus propios recursos desde su propio origen nunca activa esa restricción, ya sea que ese origen sea https://example.com o http://localhost:3000. El CLI de captura obtiene la página directamente, así que desde su perspectiva un servidor de desarrollo local y un dominio de producción son solo un origen que está solicitando. Nada más.

Esto también explica por qué importar un sitio de React o Vue a Figma e importar una app de Next.js en localhost terminan siendo el mismo flujo de trabajo con la misma herramienta. Next.js es un framework de React, y el CLI no distingue qué framework renderizó el HTML que obtuvo. Lo que sí difiere específicamente con localhost: no hay una entrada DNS pública ni una CDN delante, así que el CLI tiene que ejecutarse en una máquina que realmente pueda alcanzar la dirección de tu servidor de desarrollo. Ejecútalo en la misma máquina que el servidor de desarrollo, o en la misma red, y eso deja de ser un problema.

Lo que el CLI de captura no puede ver

El CLI de captura hace una solicitud sin autenticar a la URL que le indiques. Si tu ruta está detrás de un inicio de sesión local, ya sea NextAuth, una redirección de middleware o tu propia verificación de sesión, el CLI ve lo que ve un visitante no autenticado: una pantalla de inicio de sesión, o una redirección. No tu página real.

La solución es capturar un DOM que ya esté en el estado que quieres, en lugar de pedirle al CLI que reproduzca ese estado por sí mismo. Inicia sesión en tu propio navegador, y luego usa la exportación de HTML autocontenido desde esa página ya renderizada y ya autenticada, o guárdala como un webarchive de Safari. Ambas son entradas basadas en archivos que el plugin de UnHTML acepta directamente. No se necesita ninguna solicitud del CLI.

La misma limitación aplica a cualquier estado de datos solo de cliente. Captura un spinner, y un spinner es lo que obtienes. Si tu app local muestra uno mientras espera una API local lenta, y capturas justo en ese momento, ese spinner se convierte en la capa en Figma, no el contenido cargado. Los plugins de Figma construyen nodos de escena nativos de forma programática en lugar de colocar una imagen aplanada, así que el plugin de UnHTML construye nodos reales a partir de lo que registró la captura, no de lo que pretendías que la página terminara mostrando. La fidelidad queda limitada al estado del DOM en el momento de la captura, no a nada que el plugin pudiera inferir después.

Conclusión

Localhost no es un caso especial para UnHTML. El CLI de captura trata una dirección de servidor de desarrollo igual que cualquier otra URL, porque las mismas reglas de origen que hacen irrelevante a CORS para los propios recursos de una página aplican sin importar si esa página se sirve desde localhost o desde un dominio de producción. Los ajustes que vale la pena hacer son específicos del modo de desarrollo de Next.js: oculta el indicador de desarrollo en pantalla antes de capturar, y espera a que la página termine de hidratar para no importar un estado de carga. Una vez que la importación llega, convertir las secciones repetidas en componentes reutilizables es el siguiente paso natural, cubierto en el artículo sobre construir componentes de Figma a partir de una importación.

Preguntas frecuentes

¿Puede UnHTML importar una app de Next.js que solo corre en localhost?

Sí. El CLI de captura toma cualquier URL, incluida una dirección de localhost, y la obtiene sin límites de CORS y con scroll de página completa, generando un scene.json que arrastras al plugin de Figma. Nada en la ruta de importación distingue si la URL resuelve en internet público o en 127.0.0.1. Solo necesita ser accesible desde la máquina que ejecuta el CLI.

¿Necesito desplegar mi app de Next.js antes de importarla a Figma?

No. Desplegarla es una forma de obtener una URL estable, pero un servidor de desarrollo corriendo (next dev) en localhost es igual de capturable. La decisión más importante es build de desarrollo contra build de producción: next build && next start elimina el indicador de desarrollo en pantalla y cualquier advertencia propia del modo desarrollo del DOM, dando una captura más limpia, pero next dev también funciona bien una vez que ocultas el indicador.

¿Por qué el indicador del modo desarrollo de Next.js aparece como una capa en Figma?

UnHTML captura lo que realmente se renderiza en el DOM de la página en el momento de la captura, y el indicador de ruta en pantalla que Next.js inyecta en desarrollo es parte de ese DOM. Configura devIndicators: false en next.config.ts antes de capturar, o muévelo fuera del cuadro con la opción position, y no aparecerá en la importación.

¿El CLI de captura ve contenido detrás de un inicio de sesión en mi app local?

No por defecto. El CLI obtiene la URL de forma directa, así que solo ve lo que renderiza una solicitud sin autenticar. Para una ruta que requiere sesión, inicia sesión primero en tu propio navegador y usa una exportación de HTML autocontenido o un webarchive de Safari de esa página ya autenticada, en lugar de apuntar el CLI directamente a la URL.

¿Debería capturar una página de Next.js en modo desarrollo o construirla para producción primero?

La producción es más limpia cuando puedes permitirte el tiempo de build: sin indicador de desarrollo, sin andamiaje de Fast Refresh, y los mismos caminos de código que ven tus visitantes. El modo desarrollo es más rápido para iterar y funciona bien para la mayoría del trabajo de diseño y espaciado, siempre que ocultes el indicador y esperes a que la página hidrate por completo antes de capturarla.