Ejecutar un frontend con sus datos de ejemplo integrados

Qué es

El sitio web y el panel llevan cada uno las respuestas de una API de Northstack con datos de ejemplo, exportadas de ella, así que cada uno funciona por sí solo sin back-end: todas las pantallas del panel, y el formulario de contacto y el pago de licencias del sitio web, funcionan como con la API. Es con lo que funciona un paquete de un solo frontend nada más instalarlo, y un aviso "Sample data" al final de cada página lo indica, para que nadie lo confunda con un back-end conectado.

Cómo activarla y desactivarla

No hay ningún indicador. Lo decide un solo ajuste, NEXT_PUBLIC_API_BASE_URL, compilado al construir la aplicación:

# empty or missing: the built-in sample data, no API needed
NEXT_PUBLIC_API_BASE_URL=

# set: your API, with the /api suffix
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000/api

• Sin Docker, yarn install y yarn dev en la carpeta de la aplicación sin archivo .env funcionan con los datos de ejemplo. Un .env copiado de .env.example apunta en cambio a la API en http://localhost:8000/api.
• Con Docker, construye la imagen con --build-arg NEXT_PUBLIC_API_BASE_URL= para los datos de ejemplo. Sin ese argumento la imagen se construye para la API en http://localhost:8000/api.
• El docker compose up --build del Full Stack siempre construye ambos frontends con la dirección de la API.
• Tras cambiar el valor, reinicia yarn dev, o ejecuta yarn build de nuevo, o construye la imagen de nuevo.

• Ejecuta el panel
• Ejecuta el sitio web

El panel con datos de ejemplo

Cada respuesta se retrasa una fracción de segundo a propósito, para que se vean los estados de carga con los que se entrega el panel.

El sitio web con datos de ejemplo

La página de inicio y todas las páginas de contenido nunca llaman a la API, así que se ven igual en ambos casos. Las dos partes que sí la llaman responden en el navegador, y en el servidor para el primer pintado, desde los datos de ejemplo:

El aviso de datos de ejemplo

Mientras responden los datos de ejemplo, un aviso "Sample data" queda al final de cada página, al final de la página y no encima de ella, así que desplazado hasta el final no tapa nada. Dismiss lo oculta hasta la siguiente carga completa de la página.

La dirección de la segunda columna es con la que se construyó la aplicación. Mientras el panel funciona con los datos de ejemplo, el pie de su espacio de trabajo también dice "Sample data for demonstration."; con su propia API nunca lo dice.

Cuando una API conectada deja de responder

Con NEXT_PUBLIC_API_BASE_URL definido, los datos de ejemplo también la sustituyen cuando no se puede llegar a la API en absoluto: no está en marcha, un tiempo de espera agotado, o bloqueada porque su CORS_ORIGIN no incluye la aplicación. Una respuesta que dio la API, incluso un 404 o un 500, se muestra siempre tal cual.

• Tras un fallo se vuelve a preguntar a la API como máximo cada 30 segundos, y la aplicación vuelve a ella en cuanto responde.
• El panel muestra su aviso siempre que la sustituye.
• El sitio web la sustituye solo en el navegador: una página que renderiza su servidor nunca muestra datos de ejemplo. Su aviso se muestra en yarn dev, y en una versión de producción solo si se construyó con NEXT_PUBLIC_SAMPLE_DATA_NOTICE=always (en .env antes de yarn build, o --build-arg NEXT_PUBLIC_SAMPLE_DATA_NOTICE=always con Docker).
• Esto cubre una API que se detuvo, no una aplicación sin API: el navegador sigue probando la dirección y registra cada petición rechazada en su consola. Sin ninguna API, deja la dirección vacía.

• El aviso sigue apareciendo
• CORS y la dirección de la API

Pasar a tu API

Define NEXT_PUBLIC_API_BASE_URL con la dirección de la API con el sufijo /api, y reinicia yarn dev o construye de nuevo. La API debe incluir la dirección de la aplicación en su CORS_ORIGIN. Lo que se cambió con los datos de ejemplo se queda en ese navegador y no se envía a la API.

cp .env.example .env
yarn dev

Empezar de nuevo

Borra los datos del sitio para la dirección de la aplicación en los ajustes del navegador, o ejecuta uno de estos en la consola del navegador, y los ejemplos vuelven como se entregaron:

localStorage.removeItem("northstack_mock_db_v1"); location.reload();

localStorage.removeItem("northstack_site_mock_db_v1"); location.reload();

Quitarlo

Cuando una aplicación funcione definitivamente con tu propia API, elimina los datos de ejemplo de su código, en la carpeta de la aplicación:

yarn remove:mock

• Elimina src/lib/mock/ y el aviso (src/components/SampleDataNotice/) con sus mensajes, quita cada bloque marcado mock-api en el código, en .env.example, en el Dockerfile y en las guías de la propia aplicación, y en el Full Stack los pasajes marcados del QUICKSTART.md y el README.md de la raíz, y deja remove:mock como una nota de una línea que indica que los datos de ejemplo ya se eliminaron. En el sitio web también elimina las líneas de documentación etiquetadas {mock}. Cada archivo queda como estaría si los datos de ejemplo nunca se hubieran añadido.
• yarn remove:mock --dry-run lista los cambios sin hacerlos, y una segunda ejecución informa de que no queda nada por hacer. Funciona antes o después de yarn remove:demo.
• La aplicación necesita entonces NEXT_PUBLIC_API_BASE_URL definido. Ejecuta después yarn typecheck y yarn build.
• Elimina código y no se puede deshacer sin control de versiones, así que haz un commit antes.

Exportarlos de nuevo desde la API

Los datos de ejemplo son las propias respuestas de la API con datos de ejemplo, así que tras cambiarlos, expórtalos de nuevo. En back-end, con la API cargada y en marcha:

yarn export:mock

Inicia sesión como cada cuenta de ejemplo, lee lo que muestran las dos aplicaciones y escribe los archivos de datos del panel y del sitio web junto a él, en ../dashboard/src/lib/mock/db/seed/ y ../website/src/lib/mock/db/seed/. No se escribe nada en la base de datos. --api http://host:8000 lee otra API. Un navegador que tenga una copia anterior la descarta en su siguiente carga.

Cómo está construida