Routage & Rendu

Les routes vivent dans src/app/ sous la forme d'un arbre fondé sur les fichiers. L'imbrication des répertoires correspond à l'imbrication des URL, et des noms de fichiers spéciaux définissent ce que rend chaque segment.

Fichiers de route

Fichier Rôle
page.tsx La page. L'export par défaut est le composant Page ; props { params, searchParams, data?, actionData? }.
layout.tsx Enveloppe son sous-arbre : ({ children, route }) => Renderable. S'imbrique par répertoire. Le layout racine possède <html>.
route.ts Route API. Exportez GET / POST / PUT / DELETE / … chacune de type (request: Request) => Response.
loading.tsx Fallback Suspense pour le segment.
error.tsx Frontière d'erreur : ({ error, reset, route }).
not-found.tsx Rendue pour un 404 dans le segment.
template.tsx Comme un layout, mais une instance neuve à chaque navigation.

Un fichier de route peut aussi exporter des fonctions de données (loader / action) — voir Loaders & Actions.

Le composant Page

L'export par défaut de page.tsx reçoit :

/** @jsxImportSource @bext-stack/framework */

export default function Page({ params, searchParams, data, actionData }) {
  return <h1>Hello {params.slug}</h1>;
}

La Page ne voit jamais la request brute — seuls loader et action la voient. Lisez-y les cookies et en-têtes, puis transmettez ce dont vous avez besoin via data / actionData.

Routes dynamiques, catch-all, groupes et parallèles

Motif Signification URL d'exemple
[slug] Segment dynamique → params.slug /posts/hello
[...slug] Catch-all → params.slug (tableau) /docs/a/b/c
(group) Regroupement uniquement — aucun effet sur l'URL —
@name/page.tsx Emplacement de route parallèle nommée rendue dans un emplacement

Métadonnées

Ajoutez des balises head avec un export metadata, ou generateMetadata() quand elles dépendent de la requête ou des données chargées :

export const metadata = {
  title: "Posts",
  description: "All posts",
};

// or, dynamic:
export function generateMetadata({ params, data }) {
  return { title: data.post.title };
}

Modes de rendu

Le mode de rendu se définit dans bext.config.toml :

[rendering]
mode = "isr"        # "isr" | "ssr"
revalidate = 60     # seconds
  • ssr — rendu à chaque requête.
  • isr — régénération statique incrémentale : met en cache le rendu, revalide après revalidate secondes et sert stale-while-revalidate entre-temps.

Les valeurs ISR par défaut globales sont ttl 60 s et swr 1 h.

Info

En ISR, une route qui exporte un loader ou une action contourne automatiquement le cache ISR et se rend fraîchement à chaque requête (le SWR borne toujours l'obsolescence). Les données dynamiques, propres à chaque requête, sont donc toujours à jour sans configuration supplémentaire.

Désactiver la mise en cache

export const dynamic = "force-dynamic";

force-dynamic exclut entièrement la route de la mise en cache.

Streaming

Le SSR en streaming est automatique ou opt-in. Une route est diffusée en streaming dès que l'une de ces conditions est vraie :

  • elle importe Suspense,
  • elle a un loading.tsx,
  • un composant est un générateur asynchrone, ou
  • elle exporte export const renderingMode = "streaming".

Helpers de réponse

Le framework exporte des helpers pour construire des réponses et revalider les routes en cache :

import {
  json, html, text, xml, redirect, notFound, cached,
  revalidatePath, revalidateTag,
} from "@bext-stack/framework";
Helper Usage
json, html, text, xml Construire une Response typée avec le bon content type.
redirect Retourner une Response de redirection.
notFound Retourner une Response 404.
cached Envelopper une réponse avec une sémantique de cache.
revalidatePath(path) Invalider une route en cache par chemin.
revalidateTag(tag) Invalider des routes en cache par tag.

Retourner ou lancer une Response depuis un loader ou une action court-circuite le rendu de la page — voir Loaders & Actions.

Et ensuite

Page Ce qu'elle couvre
Loaders & Actions Chargement de données, mutations, accès à la requête/session
Présentation du SDK Structure d'un site, le SDK en loopback, l'intégration de packages
Référence CLI bext dev, bext build, bext routes
Référence de configuration bext.config.toml