Comment intégrer Lighthouse dans un projet Next.js avec GitHub

Dimitri Dumont

Développeur front-end

Dans cet article, nous allons voir comment intégrer Lighthouse CI dans un projet Next.js qui utilise l'app router et lancer des audits automatiques à chaque fois que du code est poussé sur GitHub sur une version mobile et une version desktop, sur une ou plusieurs pages.

Lighthouse est un outil très utile lorsqu'on développe un site internet ou une landing page pour une application. Il permet de mesurer la performance, l'accessibilité, les bonnes pratiques, le SEO et la PWA de votre site. C'est un outil très complet qui permet de s'assurer que votre site est bien optimisé et qu'il respecte les bonnes pratiques du web.

Il est possible d'intégrer Lighthouse dans un projet Next.js et de lancer des audits automatiques à chaque fois que vous poussez du code sur GitHub. Cela permet de s'assurer que votre site a toujours une bonne notation et que vous n'introduisez pas de régression dans les performances et l'accessibilité de votre site de façon automatique sans avoir à lancer les audits vous-même sur votre ordinateur ou votre production.

Même si ça n'a pas de réel impact sur l'intégration de Lighthouse, nous allons prendre pour exemple un projet créé avec React et Next.js v14 qui utilise l'app router de Next.js.

Pour cet article, nous allons utiliser le package @lhci/cli. Vous pouvez commencer par l'installer en tant que dépendance de développement de votre projet : yarn add -D @lhci/cli.

Une fois que le package est installé, nous allons configurer LightHouse CI. Pour cela, vous pouvez créer un fichier .lighthouserc.js à la racine du projet :

1module.exports = {
2	ci: {
3		assert: {
4			assertions: {
5				"categories:performance": ["warn", { minScore: 0.9 }],
6				"categories:accessibility": ["warn", { minScore: 0.9 }],
7				"categories:best-practices": ["warn", { minScore: 0.9 }],
8				"categories:seo": ["warn", { minScore: 0.9 }],
9			},
10		},
11		upload: {
12			target: "temporary-public-storage",
13		},
14	},
15}
16

Ce fichier permet de configurer les assertions réalisées sur chaque audit Lighthouse. Vous pouvez personnaliser les scores minimums pour chaque catégorie. Ici, nous avons défini un score minimum de 90% pour chaque catégorie.

Chaque audit est stocké dans un dossier temporaire sur le cloud de Google. Vous pouvez changer la cible de l'upload en fonction de vos besoins.

Il faut maintenant définir quelles sont les URLs à auditer et quelles sont les catégories que nous souhaitons vérifier. Pour cela, vous pouvez commencer par créer un fichier de configuration pour les audits sur desktop à la racine du projet nommé .lighthouserc.desktop.js :

1module.exports = {
2	ci: {
3		collect: {
4			startServerCommand: "yarn start",
5			url: [
6				"http://localhost:3000?desktop",
7				"http://localhost:3000/blog/hexagonal-architecture-front-end?desktop",
8			],
9			settings: {
10				chromeFlags: "--no-sandbox",
11				locale: "fr-FR",
12				preset: "desktop",
13				onlyCategories: [
14					"performance",
15					"accessibility",
16					"best-practices",
17					"seo",
18					"pwa",
19				],
20			},
21		},
22	},
23}
24

Vous pouvez faire de même avec le fichier de configuration pour les audits sur mobile :

1module.exports = {
2	ci: {
3		collect: {
4			startServerCommand: "yarn start",
5			url: [
6				"http://localhost:3000?mobile",
7				"http://localhost:3000/blog/hexagonal-architecture-front-end?mobile",
8			],
9			settings: {
10				chromeFlags: "--no-sandbox",
11				locale: "fr-FR",
12				onlyCategories: [
13					"performance",
14					"accessibility",
15					"best-practices",
16					"seo",
17					"pwa",
18				],
19			},
20		},
21	},
22}
23

Dans ces deux fichiers assez similaires, nous définissons la commande pour démarrer le serveur, ici nous utilisons la commande yarn start

Ensuite, nous définissons les URLs à auditer avec en paramètre la version afin de les distinguer (?mobile et ?desktop).

Enfin, nous configurons les différents paramètres des audits Lighthouse comme les catégories à vérifier.

Hexa web

Des conseils pour un projet web ?

Nous contacter

Avant de configurer Lighthouse avec les Github Actions, vous pouvez commencer par exécuter les audits en local grâce à des commandes.

Pour cela, il faut ajouter ces commandes dans votre fichier package.json :

1{
2"scripts": {
3    "lighthouse:desktop": "yarn build && lhci collect --config=.lighthouserc.desktop.js && lhci upload && lhci assert",
4    "lighthouse:mobile": "yarn build && lhci collect --config=.lighthouserc.mobile.js && lhci upload && lhci assert"
5  },
6 }

Vous pouvez maintenant exécuter ces commandes pour lancer les audits sur votre projet Next.js : yarn lighthouse:desktop et yarn lighthouse:mobile.

À chaque fois que vous allez exécuter un audit Lighthouse en local, des fichiers de rapport seront générés dans le dossier.lighthouseci. Vous pouvez ignorer ce dossier en l'ajoutant dans votre fichier .gitignore.

Maintenant que les audits fonctionnent en local, nous allons configurer GitHub Actions pour automatiser les audits à chaque push sur GitHub.

Pour cela, vous pouvez commencer par créer un dossier workflows dans un nouveau dossier .github à la racine de votre projet. Ce dossier contiendra les fichiers de configuration pour les GitHub Actions.

Vous pouvez commencer par créer un fichier lighthouseci.yml dans le dossier workflows :

1name: lighthouse-ci
2
3on: [push]
4
5jobs:
6  lighthouseci:
7    runs-on: ubuntu-latest
8    steps:
9      - uses: actions/checkout@v4
10      - uses: actions/setup-node@v4
11        with:
12          node-version: 20
13      - run: yarn && yarn global add @lhci/cli
14      - run: yarn build
15      - run: lhci collect --additive --config=.lighthouserc.mobile.js
16      - run: lhci collect --additive --config=.lighthouserc.desktop.js
17      - run: lhci upload
18      - run: lhci assert
19

Ce fichier de configuration permet de lancer les audits Lighthouse à chaque push sur GitHub. Il installe les dépendances nécessaires, construit le projet, lance les audits sur mobile et sur desktop, upload les résultats et vérifie les assertions.

Vous pouvez maintenant pusher votre code sur GitHub et vérifier que les audits Lighthouse sont bien lancés à chaque push.

Chaque rapport d'audit est stocké dans le cloud de Google. Vous pouvez consulter les rapports en cliquant sur chaque lien de l'étape Run lhci upload de la Github Action.

Dans cet article, nous avons vu comment configurer un projet Next.js avec Lighthouse CI et GitHub Actions pour lancer des audits automatiques à chaque push sur GitHub simplement.

Si vous le souhaitez, vous pouvez empêcher des Pull Requests d'être mergées dans le cas où les assertions de Lighthouse ne sont pas valides. Ainsi, vous vous assurez que votre site répond toujours à vos critères de performance, d'accessibilité, de bonnes pratiques, de SEO et de PWA.