Routage (orbitlab.json)

Ajoutez un fichier orbitlab.json à votre dépôt pour contrôler la façon dont les requêtes vers votre application sont traitées—redirections, réécritures, en-têtes personnalisés, comportement des barres obliques finales et URLs propres. Ces règles s’exécutent à la périphérie (devant votre application), elles s’appliquent donc avant même qu’une requête n’atteigne votre conteneur. Le fichier est analysé automatiquement à chaque déploiement. Il n’y a rien à activer.

Emplacement du fichier

Placez orbitlab.json à la racine de votre projet. Dans un monorepo, mettez-le dans le même dossier que celui défini comme Répertoire racine (ex : apps/web/orbitlab.json). Seules les clés de routage ci-dessous sont lues—toute autre clé est ignorée, vous pouvez donc conserver sans risque des paramètres non liés dans le même fichier.

Un exemple minimal

{
  "redirects": [
    { "source": "/old-blog/:slug", "destination": "/blog/:slug", "permanent": true }
  ],
  "rewrites": [
    { "source": "/api/:path*", "destination": "https://api.example.com/:path*" }
  ],
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "Strict-Transport-Security", "value": "max-age=63072000" }
      ]
    }
  ],
  "trailingSlash": false,
  "cleanUrls": true
}

Redirections

Envoyez les visiteurs d’un chemin vers un autre via une redirection HTTP.

{
  "redirects": [
    { "source": "/docs", "destination": "/documentation", "permanent": true },
    { "source": "/promo", "destination": "/sale", "statusCode": 302 }
  ]
}

Champ	Type	Description
`source`	string	Motif de chemin à faire correspondre (voir Motifs de source).
`destination`	string	Où envoyer la requête. Peut référencer les paramètres capturés.
`permanent`	boolean	`true` → `308` (par défaut), `false` → `307`. Ignoré si `statusCode` est défini.
`statusCode`	number	Code de redirection explicite (`300`–`399`). Prioritaire sur `permanent`.
`has` / `missing`	array	Conditions optionnelles (voir Conditions).

Réécritures

Servez du contenu depuis un chemin différent ou une autre origine sans changer l’URL dans le navigateur.

{
  "rewrites": [
    { "source": "/blog/:path*", "destination": "/posts/:path*" },
    { "source": "/api/:path*", "destination": "https://api.example.com/:path*" }
  ]
}

Réécriture interne — lorsque destination est un chemin absolu (ex : /posts/:path*), l’URL est réécrite et la requête continue vers votre application.
Réécriture par proxy — lorsque destination est une URL complète (ex : https://api.example.com/:path*), la requête est relayée (proxy) vers cette origine. L’en-tête Host en amont est défini sur l’hôte de destination, et les origines HTTPS sont prises en charge.

Champ	Type	Description
`source`	string	Motif de chemin à faire correspondre.
`destination`	string	Chemin absolu (interne) ou URL complète `http(s)://` (par proxy).
`has` / `missing`	array	Conditions optionnelles.

En-têtes

Attachez des en-têtes de réponse personnalisés aux requêtes correspondantes. Les règles d’en-tête n’arrêtent pas la requête—une fois les en-têtes définis, elle continue vers les réécritures et votre application.

{
  "headers": [
    {
      "source": "/assets/:path*",
      "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
    }
  ]
}

Champ	Type	Description
`source`	string	Motif de chemin à faire correspondre.
`headers`	array	Liste de paires d’en-têtes `{ "key": string, "value": string }`.
`has` / `missing`	array	Conditions optionnelles.

Barres obliques finales & URLs propres

{
  "trailingSlash": false,
  "cleanUrls": true
}

trailingSlash — false supprime la barre oblique finale (/about/ → /about) ; true l’impose (/about → /about/) pour les chemins sans extension de fichier. Les deux utilisent une redirection 308. La racine / n’est jamais affectée.
cleanUrls — redirige /page.html → /page avec un 308.

Motifs de source

Le champ source prend en charge une syntaxe de correspondance de chemin familière :

Motif	Correspond à	Exemple
`/exact/path`	Un chemin exact	`/pricing`
`:param`	Un seul segment de chemin	`/user/:id`
`:param*`	Zéro ou plusieurs segments	`/files/:path*`
`:param+`	Un ou plusieurs segments	`/files/:path+`
`:param?`	Un segment optionnel	`/blog/:slug?`
`*`	Un joker (n’importe quels caractères)	`/legacy/*`
`(regex)`	Un groupe d’expression régulière brut	`/(.*)`

Les paramètres nommés peuvent être réutilisés dans destination en réécrivant le même jeton :param. Par exemple, "/old/:slug" → "/new/:slug" transporte le segment capturé.

Conditions (has / missing)

Les redirections, réécritures et en-têtes acceptent des tableaux optionnels has et missing pour ne correspondre que lorsque certains attributs de la requête sont présents (has) ou absents (missing).

{
  "redirects": [
    {
      "source": "/dashboard",
      "destination": "/login",
      "missing": [{ "type": "cookie", "key": "session" }]
    }
  ]
}

Chaque objet de condition prend en charge :

Champ	Description
`type`	Un de `header`, `query`, `cookie` ou `host`.
`key`	Le nom de l’en-tête/paramètre/cookie. Non requis pour `host`.
`value`	Valeur exacte optionnelle. Si omise, la règle correspond uniquement à la présence.

Règles par domaine (host)

Lorsque plusieurs domaines sont attachés à votre service, utilisez une condition host pour n’appliquer une règle qu’à l’un d’eux. Une même application peut ainsi servir un contenu différent selon le sous-domaine :

{
  "rewrites": [
    {
      "source": "/:path*",
      "destination": "/tools/:path*",
      "has": [{ "type": "host", "value": "tools.example.com" }]
    },
    {
      "source": "/:path*",
      "destination": "/landing/:path*",
      "has": [{ "type": "host", "value": "www.example.com" }]
    }
  ]
}

orbitlab.json gère le routage au sein d’un seul service. Les conditions host distinguent les domaines déjà attachés à ce service—elles ne peuvent pas envoyer le trafic vers un autre service. Pour pointer un domaine vers un service précis, attachez-le à ce service depuis le tableau de bord (voir Domaines). Pour atteindre une origine externe, utilisez une réécriture dont la destination est une URL complète.

Ordre d’évaluation

Les règles sont appliquées à la périphérie dans cet ordre, puis la requête est transmise à votre application :

cleanUrls
trailingSlash
redirects
headers
rewrites
Votre application

Les redirections et les réécritures par proxy sont terminales (elles arrêtent le traitement). Les règles d’en-tête et les réécritures internes continuent la chaîne.

Gérer les règles depuis le tableau de bord

Vous pouvez aussi gérer le routage depuis le tableau de bord/l’API. Lorsque les deux existent, la configuration du tableau de bord est prioritaire sur le fichier : les listes de règles sont combinées avec les règles du tableau de bord en premier, et les indicateurs (trailingSlash, cleanUrls) utilisent la valeur du tableau de bord si elle est définie. Supprimer orbitlab.json de votre dépôt efface les règles basées sur le fichier au prochain déploiement, tandis que les règles du tableau de bord restent en place.

Limites

Pour garder le routage à la périphérie rapide, les limites suivantes s’appliquent :

Paramètre	Limite
Redirections	256
Réécritures	128
Règles d’en-tête	128
En-têtes par règle	32
Conditions `has` / `missing` par règle	16 chacune
Longueur du motif	4096 caractères

Si orbitlab.json est invalide, le déploiement continue et les règles de routage précédentes sont conservées—consultez vos journaux de build pour un avertissement de validation.

Premiers pas

Services

Domaines & DNS

Avancé

Routage (orbitlab.json)

Emplacement du fichier

Un exemple minimal

Redirections

Réécritures

En-têtes

Barres obliques finales & URLs propres

Motifs de source

Conditions (has / missing)

Règles par domaine (host)

Ordre d’évaluation

Gérer les règles depuis le tableau de bord

Limites

​Emplacement du fichier

​Un exemple minimal

​Redirections

​Réécritures

​En-têtes

​Barres obliques finales & URLs propres

​Motifs de source

​Conditions (has / missing)

​Règles par domaine (host)

​Ordre d’évaluation

​Gérer les règles depuis le tableau de bord

​Limites

Emplacement du fichier

Un exemple minimal

Redirections

Réécritures

En-têtes

Barres obliques finales & URLs propres

Motifs de source

Conditions (has / missing)

Règles par domaine (host)

Ordre d’évaluation

Gérer les règles depuis le tableau de bord

Limites