Next.js : installation

Next.js est un framework React qui ajoute le routage par fichiers, le rendu serveur, les routes d’API et l’optimisation des assets. Cette rubrique décrit Next.js avec l’App Router (dossier app/). Les exemples utilisent des noms génériques (monapp).

Choisir

Besoin	Outil
Application avec rendu serveur, SEO, API intégrée	Next.js (cette rubrique)
Application monopage sans serveur	React avec Vite
Site de contenu essentiellement statique	Astro

Prérequis

Node.js récent (voir Node.js : installation) : consulter la version minimale exigée par la version de Next.js choisie.

node --version

Créer le projet

npx create-next-app@latest monapp
cd monapp
npm run dev

L’assistant propose TypeScript, ESLint, Tailwind CSS, le dossier src/, l’App Router et l’alias d’import @/*. Le serveur de développement écoute sur http://localhost:3000. Sur un serveur distant :

npm run dev -- --hostname 127.0.0.1
ssh -N -L 3000:127.0.0.1:3000 utilisateur@serveur.exemple.com

Voir SSH : tunnels.

Structure

monapp/
├── next.config.ts          # configuration
├── package.json
├── tsconfig.json
├── public/                 # fichiers statiques (servis à la racine)
└── app/
    ├── layout.tsx          # gabarit racine (html, body)
    ├── page.tsx            # page d'accueil (/)
    ├── globals.css
    └── favicon.ico

app/layout.tsx :

import type { Metadata } from 'next';
import './globals.css';

export const metadata: Metadata = {
  title: { default: 'Mon site', template: '%s | Mon site' },
  description: 'Description du site',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="fr">
      <body>{children}</body>
    </html>
  );
}

app/page.tsx :

export default function Accueil() {
  return (
    <main>
      <h1>Bonjour Next.js</h1>
    </main>
  );
}

Scripts

Commande	Effet
`npm run dev`	Serveur de développement (rechargement à chaud)
`npm run build`	Construction de production (dossier `.next/`)
`npm run start`	Démarre le serveur de production (après `build`)
`npm run lint`	Analyse du code

Variables d’environnement

.env.local (non versionné) :

DATABASE_URL=postgres://app@127.0.0.1:5432/boutique
NEXT_PUBLIC_SITE_URL=https://exemple.com

Variable	Disponible
`DATABASE_URL`	Serveur seulement
`NEXT_PUBLIC_*`	Serveur et navigateur (valeur figée au `build`)

Ne jamais placer de secret dans une variable NEXT_PUBLIC_*. Fichiers chargés : .env, .env.local, .env.development, .env.production ; .env.local ne se versionne pas.

Configuration de base

next.config.ts :

import type { NextConfig } from 'next';

const config: NextConfig = {
  output: 'standalone', // sortie autonome pour un déploiement sur serveur
  poweredByHeader: false, // retire l'en-tête X-Powered-By
  reactStrictMode: true,
};

export default config;

Version et changements

La version installée se lit avec npm ls next. Next.js évolue vite : certaines API (par exemple l’accès asynchrone à params et cookies(), ou la mise en cache des requêtes) ont changé entre les versions majeures. Lire le guide de mise à jour de la version utilisée (voir Dépannage).

Dépannage

Symptôme	Piste
`Error: Cannot find module 'next'`	`npm install` non exécuté
Version de Node.js refusée	Installer une version prise en charge (voir Node.js : gérer les versions)
`Port 3000 is in use`	`sudo ss -tlnp \| grep 3000` ; `npm run dev -- -p 3001`
Variable d’environnement vide dans le navigateur	Préfixe `NEXT_PUBLIC_` manquant, serveur à redémarrer
`npm run start` : `Could not find a production build`	Exécuter `npm run build` avant

Ubuntu 24.04 et 26.04 : différences à connaître

Aucune propre à Ubuntu : seule la version de Node.js compte. Pour le déploiement, voir Build et déploiement.

Pour aller plus loin

Documentation : nextjs.org/docs
Suite : Routage avec l’App Router