Créer des thèmes Gatsby pour les sites Web basés sur WordPress —

{
  "privé": vrai,
  "espaces de travail" : [
    "packages/*",
    "demo"
  ]
}

mkdir packages/gatsby-theme-wp-parent
touch packages/gatsby-theme-wp-parent/package.json packages/gatsby-theme-wp-parent/index.js

{
  "nom": "@pehaa/gatsby-theme-wp-parent",
  "version": "1.0.0",
  "licence": "MIT",
  "main": "index.js"
}

"publishConfig" : {
  "accès": "public"
}

//demo/package.json
{
  "privé": vrai,
  "nom": "démo",
  "version": "1.0.0",
  "scripts": {
    "build": "gatsby build",
    "develop": "gatsby develop",
    "clean": "gatsby clean"
  }
}

"workspaces": [
  "packages/*",
  "examples/*"
]

Remarque : Vous ne pouvez pas ajouter @pehaa/gatsby- theme-wp-parent ou @pehaa/gatsby-theme-wp-child sans numéro de version. Vous devez le spécifier sous la forme @* ou @1.0.0. Sans cela, npm essaiera de récupérer le package du référentiel au lieu d'utiliser le package local. Plus tard, lorsque nous publierons nos packages avec Lerna, tous les * seront automatiquement mis à jour vers les versions du thème actuel et synchronisés.

Parent Theme

Concentrons-nous maintenant sur le thème parent et ses dépendances :

espace de travail de fil @pehaa/gatsby-theme-wp-parent add gatsby-source-wordpress gatsby-plugin-image gatsby-plugin-sharp gatsby-transformer-sharp gatsby-awesome-pagination

Notre thème parent est la responsabilité est de charger le plugin source et les trois plugins nécessaires au traitement et à l'affichage des images. Nous les chargeons tous dans le fichier gatsby-config.js.

//gatsby-config.js
module.exports = (options) => {
  retourner {
    plug-ins : [
      'gatsby-plugin-sharp', // must have for gatsby
      'gatsby-transformer-sharp', // must have for gatsby images
      'gatsby-plugin-image',
      {
        resolve: 'gatsby-source-wordpress',
        options: {
          url: `${options.wordPressUrl}/graphql`,
        },
      },
    ],
  }
}

En plus de rechercher le contenu, nous devons créer des itinéraires pour notre contenu WordPress de manière dynamique. Nous devons créer des itinéraires pour les pages statiques WordPress, les articles individuels, les archives de blogs, les archives de catégories et les archives de balises. Gatsby fournit l'API createPages dans le cadre de Gatsby Node API. Examinons le code responsable de la création de publications individuelles.

exports.createPages = async ({ graphql, actions }) => {
  const { createPage } = actions
  const postsQuery = wait graphql(`
    requête GET_POSTS {
      allWpPost(sort : {ordre : DESC, champs : date}) {
        bords {
          nœud {
            uri
            identifiant
          }
        }
      }
    }
  `)
  const posts = postsQuery.data.allWpPost.edges
  posts.forEach(({ nœud }) => {
    créer une page({
      chemin : node.uri,
      composant : path.resolve('../src/templates/post-query.js'),
      le contexte: {
        // Les données transmises au contexte sont disponibles dans les requêtes de page en tant que variables GraphQL
        // nous devons ajouter l'identifiant du message ici
        // afin que notre modèle d'article de blog sache quel article de blog il doit afficher
        identifiant : node.id
      },
    })
  })
}

Vous pouvez trouver le code complet dans ce référentiel GitHub. Vous remarquerez peut-être que cela varie en fonction du type de page. Il en va différemment pour un article, une page, ou une archive, notamment avec la pagination mise en place pour cette dernière. Toujours, il suit le même modèle :

• exécuter une requête async graphql « get items » ;
• boucler sur les éléments résultants et exécuter la fonction d'assistance createPage pour chaque élément , qui passe:
  • le chemin,
  • composant — le fichier modèle ; Gatsby doit savoir ce que chaque page doit afficher,
  • context — quelles que soient les données dont le modèle (fourni dans le champ component) pourrait avoir besoin.

Comme nous ne voulons pas. s'inquiéter de la partie de l'interface utilisateur dans le thème parent – nous la déléguons au composant que nous allons occulter dans le thème enfant.

// src/templates/post-query.js
importer { graphql } de "gatsby"
importer la publication de "../components/Post"
exporter la publication par défaut

exporter const pageQuery = graphql`
  requête ($id : chaîne !) {
    wpPost(id : { eq : $id }) {
      # interroger toutes les données utiles
    }
  }
`

Le composant Post a accès aux données de la requête de page graphql définie dans le fichier modèle. Notre composant reçoit les résultats de la requête via les accessoires en tant que props.data. Notre fichier de composant est séparé du modèle mais a accès à ses données. Avec cette configuration, nous pouvons observer le composant Post sans avoir à réécrire la requête.

// src/components/Post.js
importer React à partir de 'react'
const Post = (accessoires) => {
  return 
{JSON.stringify(props.data, null, 2)}
}
 export default Post
   
Child Theme
Maintenant, passons au thème enfant et ajoutons ses dépendances.
Remarque : J'ai choisi d'utiliser Chakra UI en tant que bibliothèque de composants, elle est basée sur emotion et est livrée avec son propre Gatsby plugin. Nous devons également installer des styles spécifiques au contenu WordPress à partir de @wordpress/block-library.
yarn workspace @pehaa/gatsby-theme-wp-child add @chakra-ui/gatsby -plugin @chakra-ui/react @emotion/react @emotion/styled @wordpress/block-library framer-motion gatsby-plugin-webfonts html-react-parser
La responsabilité du thème enfant est la partie interface utilisateur, et nous avons besoin pour remplacer la sortie nue générée par le thème parent. Pour que l'ombrage fonctionne, nous devons suivre la structure des fichiers du thème parent. Par exemple, pour remplacer le composant Post de gatsby-theme-wp-parent/src/components/Post.jsnous devons créer un Post.js fichier dans gatsby-theme-wp-child/src/@pehaa/gatsby-theme-wp-parent/components. Le dossier intermédiaire @pehaa correspond au périmètre du package gatsby-theme-wp-parent.
 
Passage d'options aux thèmes
Nous chargeons et configurons les plugins gatsby dans un fichier gatsby-config.js. Nous aurons trois fichiers de configuration dans notre configuration, un à chaque niveau, notre thème parent, le thème enfant et la démo.
├── démo
└── gatsby-config.js
paquets
├── gatsby-theme-wp-child
│ └── gatsby-config.js
└── gatsby-theme-wp-parent
└── gatsby-config.js
└── ...
Au niveau de la démo, la config charge le thème enfant comme ceci :
//demo/gatsby-config.js
module.exports = {
  plug-ins : [
    {
      resolve: '@pehaa/gatsby-theme-wp-child',
      options: {
        wordPressUrl: process.env.GATSBY_WP_URL,
        /* other options */
      },
    },
  ],
}
Comme vous pouvez le voir ci-dessus, nous passons des options au thème enfant. Ceux-ci seront disponibles dans le fichier de configuration au niveau du thème enfant. C'est possible puisque les plugins Gatsby ont une configuration exportée en tant que fonction. Ainsi, lorsque nous chargeons un plugin fournissant des options, le plugin les reçoit en argument de sa fonction de configuration. En particulier, les options que nous passons à un thème peuvent être « transférées » vers son thème de niveau parent comme suit :
// ​​gatsby-theme-wp-child/gatsby-config.js
const defaultFonts = ...
module.exports = (options) => {
  // option de structure pour extraire les polices
  const {fonts, ...rest} = options
  retourner {
    plug-ins : [
      {
        resolve: `@pehaa/gatsby-theme-wp-parent`,
        options: {
          // "forward" the options gatsby-theme-wp-child options to its parent theme
          ...rest
        }
      },
      '@chakra-ui/gatsby-plugin',
      {
        resolve: `gatsby-plugin-webfonts`,
        options: {
          fonts: fonts || defaultFonts
        },
      },
    ],
  }
}
Regardons à nouveau le code ci-dessus. Notez que nous définissons les polices au niveau du thème enfant, mais nous gardons la possibilité de les modifier via les options du thème.
//demo/gatsby-config.js
module.exports = {
  plug-ins : [
    {
      resolve: `@pehaa/gatsby-theme-wp-child`,
      options: {
        wordPressUrl: process.env.GATSBY_WP_URL,
        fonts: {
          google: [{family: "Rubik"}],
        },
      },
    },
  ],
}
Lors de la configuration de nos thèmes, nous devons nous rappeler qu'un thème n'est qu'un package et que l'utilisateur final n'accède pas directement à son code. Par conséquent, c'est une bonne idée d'anticiper et d'exposer les paramètres appropriés. Si notre thème charge un plugin qui nécessite une configuration, nous devrions probablement transmettre les options des plugins du niveau du projet (démo) jusqu'en bas.
 Regardons un exemple. Notre thème parent utilise le plugin gatsby-source-wordpress qui récupère les données de WordPress. Ce plugin est livré avec un tas d'optionsdont certaines peuvent être critiques pour le processus de construction, comme schema.requestConcurrencyou schema.timeout. Mais, encore une fois, le thème parent n'est qu'un package et l'utilisateur final ne peut pas modifier son fichier gatsby-config. Cela peut sembler évident, mais nous l'avons quelque peu manqué dans la version initiale de Gatsby WP Themes. Cependant, avec une solution rapide, l'utilisateur peut passer les options gatsby-plugin-source-wordpress à partir de la configuration du projet…
 // projet de l'utilisateur gatsby-config.js
module.exports = {
  plug-ins : [
    {
      resolve: `@pehaa/gatsby-theme-wp-child`,
      options: {
        wordPressUrl: process.env.GATSBY_WP_URL,
        gatsbySourceWordPressOptions: {},
        // ...
      },
    },
  ],
}
… via le thème enfant et parent vers le plugin de destination :
// packages/gatsby-theme-wp-parent/gatsby-config.js
module.exports = (options) => {
  retourner {
    plug-ins : [
      // ...
      {
        resolve: `gatsby-plugin-source-wordpress`,
        options: {
          url: `${options.wordPressUrl}/graphql`,
          ...options.gatsbySourceWordPressOptions
        },
      },
    ],
  }
}
Thème CSS
Les solutions CSS-in-JS qui prennent en charge les thèmes semblent bien adaptées aux thèmes Gatsby. Notre thème enfant Gatsby utilisera  Chakra UI frameworket nous personnaliserons légèrement son thème CSS. Oui, Chakra UI utilise également la notion de « thème ». Dans ce contexte, un thème  est un objet JavaScript qui stocke les valeurs de style du système de conception, les échelles et/ou les jetons de conception. Pour éviter toute confusion, je l'appellerai "thème CSS". Nous avons déjà installé les packages requis @chakra-ui avec le plugin Gatsby @chakra-ui/gatsby-plugin. Explorons le code du plugin pour découvrir comment cela fonctionne. Il encapsule en fait notre application Gatsby dans le ChakraProvider et expose le fichier src/theme.js pour l'observation, afin que nous puissions procéder comme ceci :
/* packages/gatsby- theme-wp-child/src/@chakra-ui/gatsby-plugin/theme.js */
importer { extendTheme } depuis "@chakra-ui/react"
thème const = {
  polices : {
    corps : "Karma, sans-serif",
    rubrique : "Poppins, sans-serif",
  },
  modes: {
    global: {
      corps: {
        couleur: "gris.700",
        fontSize : "xl",
      },
    },
  },
  Composants: {
    Bouton: {
      baseStyle : {
        borderRadius: "3xl",
      },
      defaultProps : {
        colorScheme : "rouge",
      },
    },
  },
}
export default extendTheme(theme)
 Encore une fois, nous avons utilisé le concept d'ombrage. L'aspect clé ici est l'emplacement où nous avons créé le fichier theme.js.
Plus tard, nous verrons comment masquer le thème CSS au niveau du projet de l'utilisateur.
Publier des thèmes avec Lerna
Une fois vos thèmes prêts, vous devez les publier. Si vous souhaitez partager votre code publiquement, vous le publierez très probablement dans le registre public npm. Et si vous n'avez jamais publié de package auparavant, vous pouvez vous familiariser avec le processus en jouant avec Verdaccio sur votre ordinateur local.
À Gatsby WP Themesnous utilisons un service premium de Cloudsmith. Cloudsmith prend en charge les registres complets pour les packages npm avec l'option premium pour les registres privés et une solution gratuite pour les registres publics. Je vais continuer avec une solution Cloudsmith gratuite. Une fois que vous avez créé votre compte, créez un nouveau référentiel ; le mien est pehaa/gatsby-wp-theming.
 
 Afin d'apporter des modifications à votre registre Cloudsmith via votre ligne de commande, vous devrez fournir vos identifiants de connexion pour ce registre. Tapez simplement :
npm login --registry=https://npm.cloudsmith.io/organistion/repository_name/
et il vous sera demandé votre nom d'utilisateur, votre mot de passe (qui est votre clé API) et votre email.
Avec un référentiel git multi-paquets, vous pouvez utiliser Lerna pour faciliter la publication. Lerna s'accorde bien avec les espaces de travail en laine. Vous pouvez installer Lerna CLI globalement avec npm install --global lerna. Pour l'initier dans notre projet, nous exécuterons la commande suivante :
lerna init --independent
La commande ci-dessus créera un fichier lerna.json à la racine du monorepo. Vous devrez ajouter les "useWorkspaces" : true et "npmClient": "yarn" manuellement ; vous devrez peut-être également spécifier le command.publish.registry s'il ne s'agit pas du npm public par défaut.
{
  "npmClient": "fil",
  "useWorkspaces": vrai,
  "version": "indépendant",
  "commande": {
    "publier": {
      "registre": "https://cloudsmith.io/organisation/repository_name"
    }
  }
}
Ensuite, la commande lerna publish publie les packages qui ont été modifiés depuis la dernière version. Par défaut, Lerna exécute des invites pour le changement de version de chaque package en cours de mise à jour. Vous pouvez ignorer les invites en exécutant :
lerna publish [major|minor|patch|premajor|preminor|prepatch|prerelease] --yes
Vous pouvez également configurer Lerna pour utiliser la Conventional Commits Specification pour déterminer le changement de version et  générez des fichiers CHANGELOG.md. Avec toutes les options disponibles, vous devriez pouvoir adapter la façon dont vous utilisez Lerna à votre flux de travail.
Utiliser un thème dans un projet
Maintenant, arrêtons le serveur de développement et prenons le point de vue de l'utilisateur. Nous allons créer un nouveau projet, gatsby-wp-sitequi implémente gatsby-theme-wp-child en tant que package installé à partir du référentiel npm. Dans notre dossier de projet, nous allons installer nos quatre dépendances : gatsbyreactreact-dom et le thème lui-même. Puisque nous avons utilisé Cloudsmith pour publier des packages à portée @pehaanous devrons ajouter un fichier .npmrc dans lequel nous spécifions un référentiel à portée @pehaa comme ceci :
mkdir gatsby-wp-site
cd gatsby-wp-site
echo "@pehaa:registry=https://npm.cloudsmith.io/pehaa/gatsby-wp-theming/" >> .npmrc
initialisation du fil -yp
fil ajouter réagir réagir-dom gatsby @pehaa/gatsby-theme-wp-child
Notre site est presque prêt. Nous n'avons qu'à créer un gatsby-config.file pour charger le thème et fournir l'URL WordPress. Une fois cela fait, nous sommes prêts à exécuter gatsby build.
// gatsby-config.js
module.exports = {
  plug-ins : [
    {
      resolve: "@pehaa/gatsby-theme-wp-child",
      options: {
        wordPressUrl: "https://yourwordpress.website"
      }
    }
  ]
}
Notre site est prêt.
 
Qu'en est-il de la personnalisation ? Nous pouvons encore profiter de l'ombrage. De plus, le niveau du projet est toujours prioritaire en termes d'ombrage. Voyons-le en action en remplaçant le composant Footer. À l'heure actuelle, notre pied de page est défini dans @pehaa/gatsby-theme-wp-child/src/components/Footer.js. Nous devons créer le dossier src et recréer la structure de fichiers suivante :
gatsby-wp-site
src
@pehaa
└── gatsby-theme-wp-child
└── composants
│ └── Footer.js
Avec la structure de fichiers ci-dessus, nous sommes prêts à fournir une nouvelle version du pied de page du site. Par exemple :
importer React à partir de "react"
importer { useStaticQuery, graphql } de "gatsby"
importer {Boîte } de "@chakra-ui/react"
const Pied de page = () => {
  données const = useStaticQuery(graphql`
    requete {
      wp {
        réglages généraux {
          Titre
        }
      }
    }
  `)
  retourner (
    
      {data.wp.generalSettings.title} - Construit avec WordPress et GatsbyJS
    
  )
}
export default Footer
Enfin, voyons comment nous pouvons travailler avec le thème CSS. Avec le code ci-dessous, correctement situé dans src/@chakra-ui/gatsby-plugin/theme.jsvous pouvez étendre le thème par défaut au sein du projet.
// src/@chakra-ui /gatsby-plugin/theme.js
importer { extendTheme } depuis "@chakra-ui/react"
thème const = {
  /* ... */
}
export default extendTheme(theme)
Dans la plupart des cas, ce n'est pas exactement ce dont vous avez besoin. Le nouveau thème CSS ignore celui de gatsby-theme-wp-childalors que vous voudriez plutôt étendre le thème CSS défini dans le thème enfant Gatsby. Ce dernier est possible puisque la fonction extendTheme permet de passer plusieurs objets. Pour le faire fonctionner, vous devez importer le thème CSS de gatsby-theme-wp-child et le passer comme deuxième argument à la fonction extendTheme :
// ​​src /@chakra-ui/gatsby-plugin/theme.js
importer le thème de "@pehaa/gatsby-theme-wp-child/src/@chakra-ui/gatsby-plugin/theme"
importer { extendTheme } depuis "@chakra-ui/react"
const ExtendedTheme = {
  polices : {
    corps : "Rubik, sans empattement",
    rubrique : "Rubik, sans empattement",
  },
  /* ... */
}
exportez le extendTheme par défaut (extendedTheme, theme) 
 
Vous pouvez voir le site en direct iciil est déployé à partir de la branche principale de ce repo GitHub.
Wrapping Up
Vous venez de voir le thème de Gatsby dans action. Avec l'approche thématique, vous pouvez rapidement configurer plusieurs sites Gatsby avec la plupart de leur code conservé dans les packages thématiques. Nous avons également vu comment séparer des parties du projet en packages et comment tirer parti de l'ombrage.
 Dans notre exemple, nous avons suivi la configuration à deux thèmes avec une relation parent-enfant entre les thèmes. Ce n'est peut-être pas toujours un choix idéal.
Parfois, vous voudrez peut-être aller assez loin avec la personnalisation de l'interface utilisateur. Dans ce cas, vous pouvez envisager de charger et d'observer directement le thème parent au lieu d'utiliser le thème enfant. Dans un scénario du monde réel, vous opteriez probablement pour quelques thèmes au niveau enfant responsables de différentes parties réutilisables de l'interface utilisateur (par exemple, commentaires, formulaires ou recherche).
Further Reading On Smashing Magazine
 (vf, yk, il)