URLs et routing

📍 Où trouver ça dans l'UI

• Domaines et HttpRoutes de l'app : Infra → onglet Architecture → URLs
• URLs réelles par env : Infra → Environments → {env} → URLs

Comment tes utilisateurs accèdent à ton app ?

Wakastart gère le routing HTTP de bout en bout : DNS → load balancer → service.

Domaines (App Domain)

App URL = sous-domaine + (préfixe d'env) + domaine

Le pattern d'URL Wakastart insère le slug de l'environnement comme préfixe entre le sous-domaine et le domaine racine — sauf pour la prod, qui n'a pas de préfixe.

textCopier
prod  →  sous-domaine "app"  +  domaine "exemple.com"            =  https://app.exemple.com
dev   →  sous-domaine "app"  +  préfixe env "dev"  +  domaine    =  https://app.dev.exemple.com

Exposer une app à la racine d'un domaine (apex)

Par défaut, une URL exige toujours un sous-domaine (app, api…). Mais si tu apportes un domaine CUSTOM (monsupersite.com), tu peux vouloir exposer ton app directement à la racine — sur monsupersite.com, sans aucun label devant. C'est ce qu'on appelle un domaine apex.

Réservé aux domaines CUSTOM. L'apex n'est pas disponible pour un domaine PLATFORM_MANAGED (*.wakastart.app), qui est partagé par toute la plateforme. Seul un domaine que tu apportes et dont tu délègues le DNS à Wakastart peut être exposé à sa racine.

AppApexUrl (Architecture) → AppApexUrlInstance (par environnement)

Comme le reste de l'architecture, l'apex se déclare une fois puis s'instancie par environnement :

Un domaine ne peut porter qu'un seul apex (contrainte d'unicité en base). Une app peut en revanche avoir plusieurs domaines CUSTOM, chacun avec son propre apex.

DNS : toujours un enregistrement A/AAAA, jamais un CNAME

Un CNAME à la racine d'une zone est structurellement invalide (RFC 1034/1912). Pour tout hostname apex, Wakastart force donc automatiquement un enregistrement A/AAAA, quel que soit le provider — tu n'as rien à configurer côté DNS, c'est géré à l'instanciation.

Avertissement obligatoire à l'instanciation

Exposer un domaine à sa racine écrit un enregistrement DNS à la racine sans sous-domaine. Or Wakastart ne vérifie pas ce qui résout déjà sur ce domaine : un site tiers déjà en production dessus (hébergé ailleurs, ou un enregistrement DNS manuel existant) peut être rendu inaccessible ou entrer en conflit.

Pour cette raison, la console affiche une modale de confirmation bloquante avant toute création d'un apex — tu dois confirmer explicitement que tu veux exposer le domaine racine. La vérification de l'usage actuel du domaine reste à ta charge.

HttpRoute = routing interne d'une URL

À une URL on attache une HttpRoute qui dit "envoie tout /api/* vers le ServiceInstance backend, tout / vers le ServiceInstance frontend". C'est du routage applicatif (équivalent d'un reverse proxy nginx, mais déclaratif).

textCopier
https://app.dev.exemple.com/api/users
            ↓
   Gateway Wakastart
            ↓
   Match HttpRoute path /api/*
            ↓
   Forward vers ServiceInstance "backend"
            ↓
   Pod backend renvoie 200 OK

URL front officielle (Primary Front URL)

Une app peut avoir plusieurs routes (AppRoute) pointant vers plusieurs services de rôle FRONT (front web, front mobile packagé en PWA, etc.). Rien ne distingue par défaut laquelle est "la" URL front de référence de l'app.

Sur l'écran Architecture → URLs, chaque route ciblant un service role: FRONT peut être désignée comme URL front officielle de l'app :

• Via l'étoile dans le tableau des routes, ou via la case à cocher du dialogue de création/modification de route.
• Une seule route active peut porter ce flag par app (contrainte imposée en base par un index partiel unique) — cocher une nouvelle route désactive automatiquement l'ancienne (comportement radio-button, pas de confirmation nécessaire).
• Le flag n'est disponible que pour une route dont le service cible a role: FRONT — pour tout autre rôle (BACK, BFF, WORKER), l'action est indisponible.

Important : ce flag est purement déclaratif/affichage. Il ne pilote aucune ressource K8s/cloud et n'a aucune influence sur les variables ROUTE_* injectées aux services — il sert uniquement à savoir "quelle URL montrer à un humain" pour cette app.

Consulter l'URL par environnement

L'endpoint GET /app-routes/primary-front-url-by-environment?appId= résout la route désignée et calcule son FQDN pour chaque environnement de l'app :

Côté dashboard, cette information est affichée via le bouton Voir les URLs sur la liste des Applications.