Next.js en production

À utiliser pour tout code dans une application Next.js 16 App Router. Les règles spécifiques à la sécurité (authentification dans les actions, CSP, en-têtes, taint) se trouvent dans nextjs-security ; les règles de conteneur dans docker-nextjs. Le skill intégré next-best-practices de Claude Code couvre en profondeur les conventions générales de fichiers, les métadonnées, l'optimisation des images et des polices ; ce skill n'ajoute que ce qui est spécifique à notre façon de construire et de livrer.

Base de référence : Next 16.4, React 19.3, Turbopack (par défaut pour dev et build), cacheComponents: true avec partialPrefetching: true, output: "standalone", typedRoutes: true. Le next.config.ts du modèle est la source de vérité.

Règles

Composants serveur par défaut ; "use client" uniquement pour l'état, les effets, les API navigateur ou les gestionnaires d'événements. Placez la directive sur la plus petite feuille qui en a besoin. Ne l'ajoutez pas parce qu'un fichier importe nuvui : les parties avec état de nuvui portent leur propre directive (voir le skill nuvui, rules/server-components.md).
```
// Erreur : toute la page est client à cause d'un seul gestionnaire
"use client";
export default function Page() { … <Select onValueChange={…} /> … }

// Correct : la page reste sur le serveur, le gestionnaire vit dans une feuille
export default async function Page() {
  const people = await getPeople();
  return <PeopleFilter people={people} />; // people-filter.tsx a "use client"
}
```
Les props passées à un composant client doivent être sérialisables : pas de fonctions (sauf les actions serveur), pas d'instances de classe.
Récupérez les données sur le serveur, dans le composant qui en a besoin. Pas de récupération avec useEffect, pas de gestionnaire de route uniquement pour alimenter votre propre page. Dédupliquez par requête avec cache() de React ; mettez en cache entre requêtes avec la règle 3.
Mettez en cache avec "use cache" + cacheLife + cacheTag ; tout le reste est dynamique. Avec les Composants Cache, rien n'est mis en cache sauf si vous le dites, et fetch n'a pas de cache implicite.
```
import { cacheLife, cacheTag } from "next/cache";

export async function getInvoice(id: InvoiceId) {
  "use cache";
  cacheLife("minutes");
  cacheTag(`invoice:${id}`);
  return db.invoice.findUnique({ where: { id } });
}
```
N'utilisez pas l'ancienne configuration de segment (export const dynamic, revalidate, fetchCache) : elle génère une erreur avec les Composants Cache. Les arguments et les valeurs fermées deviennent partie de la clé de cache, donc passez des ids, pas des objets de requête entiers. Détails, les profils et "use cache: private" : references/caching.md.
Invalidez avec updateTag dans les actions serveur, revalidateTag(tag, "max") ailleurs. updateTag(tag) permet les lectures après écriture et ne fonctionne qu'à l'intérieur d'une action serveur. Depuis un webhook ou un gestionnaire de route, utilisez revalidateTag(tag, "max") (stale-while-revalidate) ou revalidateTag(tag, { expire: 0 }). La version à un argument revalidateTag(tag) est dépréciée.
Enveloppez les données au moment de la requête dans <Suspense>, sinon la build échoue. cookies(), headers(), searchParams, connection() et les E/S non mises en cache en dehors d'une limite Suspense arrêtent le pré-rendu avec « uncached or runtime data during prerendering ». Donnez-lui une limite avec un squelette de fallback, mettez-le en cache, ou (layout racine uniquement, voir règle 14) marquez le blocage de la route avec export const instant = false. Tous les params, searchParams, cookies(), headers() sont asynchrones : attendez-les avec await.

Chaque action serveur valide ses entrées et vérifie elle-même l'autorisation. Une action serveur est un point de terminaison POST public, quelle que soit la page sur laquelle elle est écrite. Analysez FormData avec le schéma de typescript-production (valibot), puis autorisez, puis muterez, puis updateTag. Retournez un résultat typé pour les échecs attendus ; ne levez une exception que pour les bugs. L'ensemble complet des règles se trouve dans nextjs-security.

"use server";
export async function renameProject(_: State, form: FormData): Promise<State> {
  const session = await requireSession();                  // 401 si absent
  const input = v.safeParse(RenameProject, Object.fromEntries(form));
  if (!input.success) return { ok: false, errors: flatten(input.issues) };
  await assertCanEdit(session, input.output.projectId);    // 403 si non autorisé
  await db.project.update(…);
  updateTag(`project:${input.output.projectId}`);
  return { ok: true };
}

Les gestionnaires de route sont destinés aux autres clients (webhooks, mobile, santé), pas à vos propres pages. Placez-les sous app/api/. Validez le corps comme une action, retournez Response.json(...), et définissez les codes de statut intentionnellement.
Chaque application a GET /api/health, dynamique et sans dépendance. Le HEALTHCHECK Docker et les sondes Kubernetes l'appellent. Il doit répondre sans toucher à la base de données, afin qu'une dépendance lente ne redémarre pas chaque pod. await connection() l'empêche d'être pré-rendu en un fichier statique. Il se trouve dans le modèle à src/app/api/health/route.ts ; proxy.ts exclut /api/health de son filtre.
error.tsx, loading.tsx et not-found.tsx à la racine, et par segment là où l'expérience utilisateur diffère. error.tsx est un composant client ; enregistrez via onRequestError de instrumentation.ts, affichez une réessai avec reset, jamais le message d'erreur. Appelez notFound() pour les enregistrements manquants au lieu de rendre un état vide.
NEXT_PUBLIC_* est intégré à la build ; tout le reste est lu à l'exécution sur le serveur. Une seule image est promue de la branche principale à la production inchangée, donc une valeur NEXT_PUBLIC_ est la même dans tous les environnements. Mettez-y uniquement des constantes de build (nom de l'application, un DSN Sentry public identique partout). La configuration par environnement (URLs API, feature flags, secrets) est un process.env.X côté serveur, lu dans un composant serveur ou une action, et passé au client sous forme de props si nécessaire. Validez l'environnement une fois dans src/env.ts (valibot) et importez de là. N'utilisez jamais la clé env dans next.config.ts : elle est incorporée dans les bundles clients.
Marquez les modules serveur uniquement avec import "server-only". Tout ce qui lit des secrets, parle à la base de données ou importe un SDK avec des identifiants. Une importation cliente de ce module échoue alors à la build au lieu de fuiter.
after() pour le travail qui ne doit pas retarder la réponse (journaux d'audit, analytics, préchauffage du cache). Lisez cookies()/headers() avant d'appeler after, pas à l'intérieur. Il s'exécute dans le même processus, donc le pod a besoin de son délai de grâce SIGTERM (le chart définit terminationGracePeriodSeconds).
Instrumentez avec src/instrumentation.ts : registerOTel + onRequestError. OpenTelemetry via @vercel/otel, exportateur configuré par les variables d'environnement standard OTEL_EXPORTER_OTLP_* à l'exécution. Voir references/observability.md.
Gardez output: "standalone" et n'importez jamais depuis l'extérieur du workspace. Le runner Docker copie uniquement .next/standalone, .next/static et public. Dans le monorepo, server.js atterrit à .next/standalone/apps/<app>/server.js ; la racine du workspace est trouvée à partir de pnpm-lock.yaml, donc ne définissez pas outputFileTracingRoot ou turbopack.root sauf si la build prévient. Détails de l'auto-hébergement (multi-réplicas, clés d'actions serveur, deploymentId) : references/self-hosting.md.
Le layout racine lit le nonce CSP, donc l'application s'affiche par requête. Le proxy.ts du modèle définit un CSP basé sur un nonce et src/app/layout.tsx a export const instant = false. C'est un compromis délibéré : les nonces et les shells statiques pré-rendus ne peuvent pas coexister, et pour les applications métier connectées, un CSP strict l'emporte. La mise en cache des données avec "use cache" fonctionne toujours. Ne supprimez aucune des deux parties sans lire la règle 4 de nextjs-security.
Styles : SCSS BEM global, importé par le composant. Turbopack compile Sass avec le package sass ; sassOptions.loadPaths: ["src/styles"] rend @use "abstracts" accessible depuis n'importe quelle profondeur. Pas d'imports ~, pas de sassOptions.functions. Règles dans scss-bem.
Images via next/image, polices via next/font. sharp est fourni avec Next pour l'optimiseur ; l'image du runner n'a besoin d'aucun package supplémentaire. Les images distantes nécessitent images.remotePatterns avec un nom d'hôte exact.
Vérifiez la taille du bundle avec pnpm next analyze (l'analyseur de Turbopack ; @next/bundle-analyzer est réservé à webpack). Chargez paresseusement les widgets clients lourds (éditeur nuvui, cartes, graphiques sous la ligne de flottaison) avec next/dynamic.
Utilisez les routes typées et les types générés. typedRoutes: true vérifie <Link href> ; PageProps<"/invoices/[id]"> et LayoutProps sont globaux après next typegen (exécuté automatiquement par next dev/next build). N'écrivez pas manuellement les types params.
Pas de next lint. Il a été supprimé dans la version 16. Biome se charge du lint (voir biome) ; TypeScript vérifie avec tsc --noEmit par package.

Vérifier

pnpm typecheck
pnpm lint
pnpm build                      # turbo run build : échoue en cas d'erreurs de pré-rendu, d'erreurs de type, d'erreurs Sass
pnpm --filter <app> start &     # puis :
curl -fsS localhost:3000/api/health

Nuvraxis/nuvraxis-plugins

Qu'est-ce que nuvraxis-plugins ?

Demander à votre IA préférée

Documentation

Next.js en production

Règles

Vérifier

Sources

Individual skills in this repo