Lancer un frontend sur ses données d'exemple intégrées

Comment le site et le tableau de bord fonctionnent chacun sans aucune API, ce qui y marche, ce que dit l'avis Sample data, ce qui se passe quand une API connectée cesse de répondre, et comment passer à votre API ou retirer les données d'exemple.

Pour le pack Full Stack

Description

Le site et le tableau de bord embarquent chacun les réponses d'une API Northstack initialisée, exportées d'elle, si bien que chacun fonctionne seul sans back-end : chaque écran du tableau de bord, ainsi que le formulaire de contact et le paiement des licences du site, se comportent comme avec l'API. C'est ce sur quoi tourne d'emblée un pack de frontend seul, et un avis « Sample data » en bas de chaque page le signale, pour que personne ne le prenne pour un back-end connecté.

L'activer et la désactiver

Il n'y a pas d'option. Un seul réglage décide, NEXT_PUBLIC_API_BASE_URL, compilé au moment du build de l'application :

.env

# 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

Sans Docker, yarn install et yarn dev dans le dossier de l'application sans fichier .env fonctionnent sur les données d'exemple. Un .env copié depuis .env.example pointe plutôt vers l'API sur http://localhost:8000/api.
Avec Docker, construisez l'image avec --build-arg NEXT_PUBLIC_API_BASE_URL= pour les données d'exemple. Sans cet argument, l'image est construite pour l'API sur http://localhost:8000/api.
Le docker compose up --build du Full Stack construit toujours les deux frontends avec l'adresse de l'API.
Après avoir changé la valeur, redémarrez yarn dev, ou relancez yarn build, ou reconstruisez l'image.

Le tableau de bord sur des données d'exemple

Domaine	Sur les données d'exemple
Connexion	N'importe quel mot de passe permet de se connecter. `owner@`, `admin@`, `member@`, `billing@`, `platform@` et `support@northstack.example` ouvrent chacun ce compte du seed et son rôle, un compte créé sur la page d'inscription se connecte comme lui-même, et tout autre e-mail ouvre celui du propriétaire. Les champs vides ou mal formés sont refusés comme l'API les refuse.
Données	Forma Studio et Monogram en entier, avec leurs projets, tableaux, fichiers, équipe, invitations, matrice de rôles, facturation et factures, clés d'API, activité et conversations passées de l'assistant, ainsi que les organisations, utilisateurs, personnel, rôles et paramètres de la plateforme. Chaque date est avancée, si bien que l'activité de cette semaine reste celle de cette semaine.
Modifications	Réel : créer un projet, déplacer une carte, inviter quelqu'un, modifier la matrice de rôles, acheter une formule par le paiement test ou suspendre une organisation change les données, et survit à un rechargement, dans ce navigateur seulement.
Permissions	Vérifiées comme l'API les vérifie, d'après la matrice de rôles de chaque espace de travail, si bien que chaque rôle voit exactement ce qu'il verrait avec l'API.
Facturation	Comme sur une API sans clés Stripe : un passage à une formule supérieure passe par le paiement test intégré, un retour à une formule inférieure est planifié pour le renouvellement et Keep l'annule. Les factures se téléchargent en PDF.
E-mail	Aucun n'est envoyé. Un lien d'invitation ou de réinitialisation du mot de passe est écrit dans la console du navigateur à la place, et y fonctionne.
Mises à jour en direct	Aucune : la cloche montre l'activité déjà présente dans l'exemple.
Clés d'API	Créées et révoquées, avec le secret montré une fois, mais une clé n'authentifie rien, puisqu'il n'y a pas d'API.
Assistant IA	Ses conversations passées et la carte de tâches du seed s'affichent. Une nouvelle question demande d'abord une clé de fournisseur, puis répond que l'assistant a besoin de l'API ; aucun modèle n'est appelé.

Chaque réponse est retardée d'une fraction de seconde exprès, pour que les états de chargement fournis avec le tableau de bord soient visibles.

Le site sur des données d'exemple

La page d'accueil et chaque page de contenu n'appellent jamais l'API : elles ont donc le même aspect dans les deux cas. Les deux parties qui l'appellent répondent dans le navigateur, et sur le serveur pour le premier affichage, à partir des données d'exemple :

Domaine	Sur les données d'exemple
Paiement des licences	Vérifié comme l'API le vérifie. La carte comme PayPal passent par le Test checkout du site lui-même sur `/checkout/test` : Pay marque la commande comme payée et le reçu affiche une clé de licence ; Cancel payment l'annule. Le montant est le prix de la licence, quoi qu'envoie le navigateur.
Formulaire de contact	Vérifié champ par champ comme l'API le vérifie, et traité avec un succès. Rien n'est envoyé nulle part.
Ce qu'envoient les visiteurs	Les commandes et les messages ne sont gardés que dans ce navigateur, si bien qu'un reçu affiche encore sa clé après un rechargement.
E-mail et limites	Aucun reçu ni message n'est envoyé par e-mail, et les limites par adresse de l'API sur les deux formulaires ne s'appliquent pas.

L'avis Sample data

Tant que les données d'exemple répondent, un avis « Sample data » se trouve en bas de chaque page, à la fin de la page plutôt que par-dessus, si bien qu'en bas de page il ne cache rien. Dismiss le masque jusqu'au prochain chargement complet de la page.

Application	Sans API définie	Avec une API définie qui ne répond pas
Tableau de bord (chaque page, la page de connexion comprise)	« No API is connected, so this dashboard runs on built-in sample data and your changes stay in this browser. Any password signs in: owner@, admin@, member@, billing@, platform@ or support@northstack.example opens that role. »	« The API at http://localhost:8000/api is not answering, so this dashboard is showing built-in sample data, not your workspace's. Changes made now stay in this browser. Start the API, then reload this page. »
Site	« No API is connected (NEXT_PUBLIC_API_BASE_URL is empty), so the site runs on built-in sample data: the contact form and the license checkout answer in this browser and send nothing. Set NEXT_PUBLIC_API_BASE_URL in .env to use your API. »	« The API at http://localhost:8000/api is not answering, so this site is showing built-in sample data. Orders and messages sent now stay in this browser. Start the API, then reload this page. »

L'adresse de la deuxième colonne est celle avec laquelle l'application a été construite. Tant que le tableau de bord fonctionne sur les données d'exemple, son pied de page d'espace de travail indique aussi « Sample data for demonstration. » ; sur sa propre API, jamais.

Quand une API connectée cesse de répondre

Avec NEXT_PUBLIC_API_BASE_URL définie, les données d'exemple prennent aussi le relais quand l'API est totalement injoignable : arrêtée, délai dépassé, ou bloquée parce que son CORS_ORIGIN ne liste pas l'application. Une réponse donnée par l'API, même un 404 ou un 500, est toujours affichée telle quelle.

Après un échec, l'API est interrogée de nouveau toutes les 30 secondes au plus, et l'application y revient dès qu'elle répond.
Le tableau de bord affiche son avis chaque fois qu'il prend le relais.
Le site ne prend le relais que dans le navigateur : une page que rend son serveur n'affiche jamais de données d'exemple. Son avis s'affiche avec yarn dev, et dans un build de production seulement s'il a été construit avec NEXT_PUBLIC_SAMPLE_DATA_NOTICE=always (dans .env avant yarn build, ou --build-arg NEXT_PUBLIC_SAMPLE_DATA_NOTICE=always avec Docker).
Cela vaut pour une API qui s'est arrêtée, pas pour une application sans API : le navigateur continue d'essayer l'adresse et consigne chaque requête refusée dans sa console. Sans aucune API, laissez l'adresse vide.

Passer à votre API

Définissez NEXT_PUBLIC_API_BASE_URL avec l'adresse de l'API suivie du suffixe /api, puis redémarrez yarn dev ou reconstruisez. L'API doit lister l'adresse de l'application dans son CORS_ORIGIN. Ce qui a été modifié sur les données d'exemple reste dans ce navigateur et n'est pas envoyé à l'API.

Terminal

cp .env.example .env
yarn dev

Repartir de zéro

Effacez les données du site pour l'adresse de l'application dans les paramètres du navigateur, ou lancez l'une de ces commandes dans la console du navigateur, et les exemples reviennent tels qu'ils ont été livrés :

Console du navigateur, tableau de bord

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

Console du navigateur, site

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

Le supprimer

Une fois qu'une application tourne définitivement sur votre propre API, supprimez les données d'exemple de son code, dans le dossier de l'application :

Terminal

yarn remove:mock

Il supprime src/lib/mock/ et l'avis (src/components/SampleDataNotice/) avec ses messages, retire chaque bloc marqué mock-api dans le code, dans .env.example, dans le Dockerfile et dans les guides de l'application, et dans le Full Stack les passages marqués du QUICKSTART.md et du README.md de la racine, et laisse remove:mock sous forme d'une note d'une ligne indiquant que les données d'exemple sont déjà supprimées. Sur le site, il supprime aussi les lignes de documentation marquées {mock}. Chaque fichier se lit comme si les données d'exemple n'avaient jamais été ajoutées.
yarn remove:mock --dry-run liste les changements sans les faire, et une seconde exécution ne signale plus rien à faire. Il fonctionne avant ou après yarn remove:demo.
L'application a alors besoin de NEXT_PUBLIC_API_BASE_URL définie. Lancez ensuite yarn typecheck et yarn build.
Elle supprime du code et ne peut pas être annulée sans gestion de versions : faites donc d'abord un commit.

Les exporter de nouveau depuis l'API

Les données d'exemple sont les réponses de l'API initialisée elle-même : après avoir modifié le seed, exportez-les de nouveau. Dans back-end, avec l'API initialisée et en cours d'exécution :

Terminaldans back-end

yarn export:mock

Il se connecte avec chaque compte du seed, lit ce que montrent les deux applications, et écrit les fichiers de seed du tableau de bord et du site à côté, dans ../dashboard/src/lib/mock/db/seed/ et ../website/src/lib/mock/db/seed/. Rien n'est écrit dans la base. --api http://host:8000 lit une autre API. Un navigateur qui garde une ancienne copie l'abandonne à son prochain chargement.

Comment il est construit

Inclus avec votre achat. Connectez-vous pour le lire, ou ouvrez-le dans votre téléchargement.

Où vivent les données d'exemple dans chaque application, comment une requête les atteint, et comment les garder synchronisées avec votre API.

Se connecter pour lire Voir le template