Tutoriel pour configurer et déployer un projet Next.js

Next.js est un framework React qui permet de créer des sites internet et des applications web. Il est très utilisé dans le monde du développement web, que ce soit pour des projets personnels ou professionnels. De nombreuses start-ups l'utilisent pour créer une application ou un SaaS. Malheureusement, trop de projets sont lancés sur de mauvaises bases, ce qui engendre des régressions à chaque mise à jour et des coûts de développement de plus en plus élevés au fil du temps.

Dans cet article, nous allons découvrir comment configurer un projet Next.js pour démarrer sur de bonnes bases. Nous allons utiliser ESLint, Prettier, Jest, Tailwind CSS, Husky et lint-staged. Les commandes et les fichiers de configuration correspondent à Next.js 16.

En plus de la configuration des librairies, nous allons voir comment versionner notre projet avec GitHub. Enfin, nous allons mettre en place une CI grâce aux GitHub Actions et déployer notre projet sur Vercel.

Création du projet Next.js

Pour commencer, nous allons créer notre projet Next.js avec la dernière version disponible. Next.js 16 demande Node.js 20.9 au minimum. Ouvrez un terminal et exécutez la commande suivante :

npx create-next-app@latest

Après le nom du projet, la commande propose les réglages recommandés : TypeScript, ESLint, Tailwind CSS, App Router et un fichier AGENTS.md destiné aux agents de code. Je vous conseille de choisir « customize settings » pour activer en plus le dossier src. Séparer votre code des fichiers de configuration fait gagner du temps de recherche tout au long du projet.

Développer correctement avec TypeScript

TypeScript est installé et configuré dès la création du projet. Sa configuration se trouve dans le fichier tsconfig.json : le mode strict est activé et l'alias @/* pointe vers le dossier src. En fonction de vos préférences et de votre projet, vous pouvez modifier cette configuration.

Styliser son application avec Tailwind CSS

Depuis Tailwind CSS v4, le fichier tailwind.config.js n'existe plus sur un nouveau projet. La configuration se fait dans le CSS : le fichier src/app/globals.css importe Tailwind, et le thème (couleurs, polices, animations) se déclare avec la directive @theme.

@import "tailwindcss";
 
@theme {
  --color-primary: #1d4ed8;
}

Cette variable génère les classes bg-primary, text-primary ou border-primary. Les plugins se déclarent dans le même fichier avec la directive @plugin.

Améliorer la lisibilité de son code

Avoir un code lisible et correctement structuré est important pour la maintenabilité d'un projet. Pour cela, nous allons utiliser ESLint, installé par défaut sur un nouveau projet Next.js. Cette librairie permet de détecter des erreurs dans le code et de les corriger automatiquement lorsque c'est possible.

Deux changements par rapport aux anciennes versions de Next.js : la commande next lint a été supprimée dans Next.js 16, et next build ne lance plus le linter. Le script lint appelle directement ESLint, configuré dans le fichier eslint.config.mjs au format flat config.

En plus d'ESLint, nous allons utiliser Prettier, un formateur de code. ESLint vérifie la qualité du code, Prettier s'occupe de la mise en forme. Pour éviter que les deux se contredisent, nous installons aussi eslint-config-prettier, qui désactive les règles ESLint de formatage :

yarn add -D prettier eslint-config-prettier

Créez ensuite un fichier .prettierrc à la racine de votre projet. C'est dans ce fichier que vous allez configurer Prettier. Voici un exemple de configuration :

{
    "semi": false,
    "singleQuote": false,
    "tabWidth": 4,
    "useTabs": true
}

Ajoutez eslint-config-prettier dans le fichier eslint.config.mjs généré par Next.js, après les configurations de Next.js :

import { defineConfig, globalIgnores } from "eslint/config"
import nextVitals from "eslint-config-next/core-web-vitals"
import nextTs from "eslint-config-next/typescript"
import prettier from "eslint-config-prettier/flat"
 
const eslintConfig = defineConfig([
  ...nextVitals,
  ...nextTs,
  prettier,
  globalIgnores([".next/**", "out/**", "build/**", "next-env.d.ts"]),
])
 
export default eslintConfig

En plus de la commande yarn lint, vous pouvez créer une nouvelle commande yarn format pour formater manuellement tous les fichiers TypeScript & JavaScript dans le dossier src de votre code. Pour cela, il suffit de modifier votre fichier package.json :

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint",
    "format": "prettier --write 'src/**/*.{tsx,ts,jsx,js}'"
  }
}

Pour éviter de devoir penser à linter et formater son code, Husky et lint-staged font ce travail automatiquement avant chaque commit. Installez les deux librairies avec la commande suivante :

yarn add -D husky lint-staged

Puis exécutez la commande suivante pour initialiser Husky :

npx husky init

Cette commande ajoute un script prepare au package.json et crée le fichier .husky/pre-commit. Remplacez son contenu par :

npx lint-staged

Ajoutez ensuite cette configuration dans votre fichier package.json :

{
    "lint-staged": {
        "src/**/*.{js,jsx,ts,tsx,json}": [
            "npx prettier --write",
            "npx eslint --fix"
        ]
    }
}

Désormais, avant chaque commit, les fichiers modifiés seront lintés et formatés.

Pour aller plus loin (tri des imports, nommage des fichiers, protection de l'architecture), j'ai détaillé ma configuration dans l'article ESLint, Prettier, Husky : automatiser la qualité du code.

Tester son application avec Jest

Pour tester votre code, vous pouvez utiliser le framework Jest. Pour cela, installez Jest avec la commande suivante :

yarn add -D jest @types/jest ts-jest

Une fois Jest installé, nous allons utiliser la librairie ts-jest pour configurer Jest avec Typescript, notamment pour utiliser les alias. Pour cela, créez un fichier jest.config.ts à la racine de votre projet :

import { pathsToModuleNameMapper } from "ts-jest"
import { compilerOptions } from "./tsconfig.json"
import type { JestConfigWithTsJest } from "ts-jest"
 
const jestConfig: JestConfigWithTsJest = {
	roots: ["<rootDir>"],
	preset: "ts-jest",
	testEnvironment: "node",
	modulePaths: ["<rootDir>"],
	moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, {
		prefix: "<rootDir>/",
	}),
	transform: {
		"^.+\\.(ts|tsx)?$": "ts-jest",
	},
}
export default jestConfig

Vous pouvez désormais écrire des tests en Typescript dans votre projet avec Jest.

Implémenter une CI/CD avec GitHub

GitHub est une plateforme permettant de versionner son projet en ligne. Elle propose également la possibilité d'intégrer une CI/CD à son projet grâce aux GitHub Actions.

Pour créer un dépôt, rendez-vous sur le lien suivant et remplissez les différentes informations de votre projet : https://github.com/new

Vous pouvez ensuite créer un fichier .github/workflows/main.yml à la racine de votre projet. Ce fichier définit un workflow GitHub Actions, c'est-à-dire un script qui s'exécute à chaque push ou pull request sur votre projet. Voici un exemple :

name: Main GitHub Actions
 
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
 
jobs:
  test-job:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7
 
      - name: Use Node 24
        uses: actions/setup-node@v7
        with:
          node-version: 24
 
      - name: Install dependencies
        run: yarn install
 
      - name: Compile TypeScript
        run: yarn tsc
 
      - name: Run tests
        run: yarn jest

Ce workflow s'exécute à chaque push sur la branche main et sur chaque pull request qui pointe sur la branche main. Il installe les dépendances, compile TypeScript puis exécute les tests du projet avec Jest.

Déployer son projet en ligne avec Vercel

Maintenant que nous avons un projet créé, linté, formaté, testé et versionné, il ne reste plus qu'à le mettre en ligne. Pour cela, nous allons utiliser Vercel, la plateforme de déploiement de l'entreprise qui développe Next.js. Les fonctionnalités du framework comme l'optimisation des images ou l'ISR y fonctionnent sans configuration.

Pour déployer un projet sur Vercel, rendez-vous sur cette page : https://vercel.com/new et suivez les instructions. Vous pouvez également utiliser l'interface en ligne de commande Vercel pour déployer votre projet.

Une fois connecté, vous pouvez choisir le projet que vous souhaitez déployer. Si vous avez déjà un projet sur GitHub, vous pouvez le sélectionner. Sinon, vous pouvez créer un nouveau projet.

À chaque push sur votre branche git principale, un déploiement s'effectuera sur Vercel. Par défaut, Vercel crée un environnement de prévisualisation pour chaque pull request ouverte sur GitHub. C'est pratique pour tester ou faire tester vos changements à des personnes de votre équipe avant de les fusionner.

FAQ

Faut-il utiliser yarn ou npm pour un projet Next.js ?

Les deux fonctionnent parfaitement avec Next.js. Yarn offre un cache plus performant et des installations plus rapides. npm est le gestionnaire par défaut de Node.js. Le choix dépend des préférences de l'équipe et des contraintes du projet.

Pourquoi utiliser Husky et lint-staged plutôt que de linter manuellement ?

L'automatisation garantit que le code est toujours formaté avant chaque commit. Sans ces outils, les développeurs peuvent oublier de lancer les commandes de lint et de formatage. Husky intercepte les commits et lint-staged ne traite que les fichiers modifiés pour optimiser les performances.

Est-il possible de déployer un projet Next.js ailleurs que sur Vercel ?

Oui. Next.js se déploie sur un serveur Node.js, dans un conteneur Docker, ou sur des plateformes comme AWS, Google Cloud, Netlify ou Railway. Vercel reste la solution la plus simple car elle est développée par les créateurs de Next.js.

Comment configurer des alias de chemins dans Next.js avec TypeScript ?

La configuration se fait dans le fichier tsconfig.json via les options baseUrl et paths. Cette configuration permet d'utiliser des imports absolus comme @/components au lieu de chemins relatifs complexes. Jest nécessite une configuration supplémentaire via ts-jest pour résoudre ces alias.

J'espère que cet article vous sera utile pour démarrer votre projet Next.js sur de bonnes bases. Si vous avez une question ou besoin d'un accompagnement pour démarrer votre projet, nous pouvons en discuter.

Si vous souhaitez découvrir comment architecturer votre projet Next.js, je vous invite à lire mon article sur l'architecture hexagonale en front-end.