Gatsby v3 l'essentiel

Soyez conscients qu'il ne s'agit pas d'une liste exhaustive. Cliquez sur la flèche de gauche pour replier le contenu.

Permalien pour la section Concepts Concepts

Gatsby est un framework phénoménal qui facilite l’utilisation de technologies de pointe.

Hydratation React Gatsby utilise des APIs React DOM côté serveur pour générer des contenus HTML statiques et ces pages sont au final ré-hydratées dans une application React. Une partie du code JavaScript utilisé pour générer les pages Gatsby est réutilisée dans le navigateur où certaines API DOM comme window sont disponibles.
GraphQL Gatsby utilise ce langage de requête pour mettre les données à disposition dans le navigateur lorsque les composants en ont besoin
Webpack Gatsby utilise ce gestionnaire de modules JavaScript.
Routage Il s'agit du mécanisme pour charger les contenus d'un site ou d'une application qui correspondent à la requête réseau, le plus souvent une URL. Gatsby va créer des chemins pour accéder aux contenus et gérer le routage dynamique en préchargeant les ressources (prefetching).
Plugins Les paquets Node.js implémentés dans les APIs Gatsby pour rajouter des fonctionnalités et filtrer les données.
Thèmes Les thèmes sont des plugins spéciaux avec leur propre gatsby-config.js.
Shadowing des thèmes Vous pouvez écraser des composants, des objets, et tout ce qui se trouve dans le dossier src d'un thème. Vous trouverez plus de détails ici.

Permalien pour la section Migration de la v2 vers v3 Migration de la v2 vers v3

La V3 est une version majeur avec des changements importants qui peuvent provoquer des erreurs lors de la migration.

Mettre à jour Gatsby yarn add gatsby@latest
Mettre à jour toutes les dépendences yarn upgrade-interactive --latest
Le guide officiel La communauté Gatsby est vraiment très forte pour rédiger des documentations efficaces. Vous pouvez lire le guide de migration

Permalien pour la section Core files Core files

gatsby-config.js Le fichier de configuration principal qui contient:
  • la liste des extensions et thèmes (paquets NPM, plugins locaux, etc)
  • l'objet siteMetadata
  • certains mappings
gatsby-node.js Gatsby charge ce fichier après les extensions, le cache, le bootstrap, et le schéma GraphQL. Vous pouvez accéder à l'API CreatePages pour ajouter vos propres noeuds (~ URLs).
gatsby-ssr.js Ce fichier contrôle une étape spéciale, quand Gatsby gère par lui-même l'équivalent d'un serveur Node (~ compilation) pour transformer le code React en fichier HTML statiques. Vous pouvez alors accéder aux APIs SSR
gatsby-browser.js Les APIs Browser permettent de cibler certains événements précis de Gatsby dans le navigateur. C'est là que vous pouvez interagir avec le côté client.

Permalien pour la section Extensions Extensions

Gatsby a un écosystème très riche avec des extensions utiles.

Ajouter une extension Installer le paquet Node.js et ouvrez le fichier gatsby-config.js:
module.exports = {
  siteMetadata: {},
  plugins: ["gatsby-plugin-image"],
}
Notez que vous aurez souvent des lignes additionnelles pour la configuration de chaque extension.
Extensions indispensables

Il y a une extension pour Google Analytics aussi

Les extensions pour des approches alternatives Attention à la compatibilité avec la v3 (voir v4 à l'heure où j'écris 😝) et aux éventuels incompatibilités:

Permalien pour la section CLI CLI

Créer le prochain site tendance avec Gatsby Vous pouvez démarrer avec gatsby new the-next-big-thing
Démarrer un serveur local Lancez gatsby develop -o, l'option -o ouvre le site dans le navigateur dans un nouvel onglet.
Supprimer le cache et le dossier public Lancez gatsby clean.
Compiler le site Lancez gatsby build.
Lancer un serveur local avec le site compilé Lancez gatsby serve -o, l'option -o ouvre le site dans le navigateur dans un nouvel onglet.
Tester le site localement, par exemple sur un mobile Lancez gatsby develop -H 0.0.0.0 -p 8000

Permalien pour la section Flags Flags

Vous pouvez ajouter des flags pour personnaliser le dév:

// dans le fichier gatsby-config.js
module.exports = {
  flags: {
    FAST_DEV: true,
  },
}
PRESERVE_WEBPACK_CACHE Conserver le cache webpack quand on modifie des fichiers centraux comme gatsby-node.js et gatsby-config.js car ce besoin est assez rare.
FAST_DEV Accélérer le démarrage du server local
DEV_SSR Detecter les bugs SSR et les fixer sans avoir besoin de lancer un build (compilation).
QUERY_ON_DEMAND Lancer les requêtes à la demande plutôt que systématiquement et tout le temps.
LAZY_IMAGES Eviter le traitement sur les images hormis quand elles sont explicitement demandées depuis le navigateur.
PRESERVE_FILE_DOWNLOAD_CACHE Evitez de re-télécharger systématiquement tous les fichiers lorsque vous modifier des fichiers centraux comme gatsby-node.js et gatsby-config.js car c'est finalement assez rare d'avoir ce besoin.
FAST_REFRESH Pour utiliser le Fast Refresh React au lieu du classique react-hot-loader ce qui permet un rafraîchissement quasi instantané.
PARALLEL_SOURCING Parallèliser les sources depuis des APIs externes ou des CMS au lieu de faire des requêtes successives.
FUNCTIONS Fonctions Serverless pour le cloud Gatsby (offre commerciale d'hébergement)

Permalien pour la section Source from CMS Source from CMS

Gastby peut charger assez facilement des contenus depuis divers CMS et APIs.