Extension de Webpack dans la chaîne d’outils de SharePoint Framework

Article
03/21/2023

Webpack est un programme de regroupement de modules JavaScript qui prend vos fichiers JavaScript et leurs dépendances et génère un ou plusieurs fichiers JavaScript afin que vous puissiez charger différentes parties de code selon les cas de figure.

La chaîne d’outils de l’infrastructure utilise CommonJS pour le regroupement. Cela vous permet de définir les modules et l’endroit où vous souhaitez les utiliser. La chaîne d’outils utilise également SystemJS, un chargeur de modules universel, pour charger vos modules. Cela vous aide à définir l’étendue d’application de votre composant WebPart en faisant en sorte que chaque composant WebPart soit exécuté dans son propre espace de noms.

Il est également très utile d’ajouter à la chaîne d’outils SharePoint Framework une tâche permettant d’étendre la configuration Webpack avec des plug-ins et des modules de chargement personnalisés.

Utilisation de chargeurs Webpack

Il existe de nombreux cas dans lesquels vous pouvez importer et utiliser des ressources autres que JavaScript lors du développement, ce qui se fait généralement avec des images ou des modèles. Un chargeur Webpack convertit la ressource en un élément pouvant être utilisé par votre application JavaScript, ou fournit une référence simple que votre application JavaScript peut comprendre.

Par exemple, un modèle Markdown peut être compilé et converti en une chaîne de texte, tandis qu’une ressource image peut être convertie en une image Base64 incorporée ou être référencée sous la forme d’une URL et copiée vers votre répertoire dist pour le déploiement.

Il existe de nombreux chargeurs utiles, dont plusieurs sont déjà utilisés par la configuration Webpack standard de SharePoint Framework, par exemple :

html-loader
json-loader
loader-load-themed-styles

L’extension de la configuration Webpack de l’infrastructure à l’aide de chargeurs personnalisés est un processus simple qui est décrit dans la rubrique sur les Chargeurs Webpack.

Exemple : Utilisation du package markdown-loader

En guise d’exemple, nous allons utiliser le chargeur markdown-loader. Ce chargeur permet de spécifier un fichier .md et de le lire sous forme de chaîne au format HTML.

Vous pouvez télécharger l’exemple complet dans samples/js-extend-webpack.

Étape 1 : installer le package

Spécifiez le chargeur markdown-loader dans le projet :

npm i --save markdown-loader

Étape 2 : configurer Webpack

Maintenant que nous avons installé le package, nous allons configurer Webpack dans SharePoint Framework afin d’inclure markdown-loader.

La documentation sur markdown-loader montre comment étendre la configuration Webpack pour inclure le chargeur :

{
  module: {
    rules: [
      {
        test: /\.md$/,
        use: [
          {
            loader: 'html-loader'
          },
          {
            loader: 'markdown-loader',
            options: {
              /* options for markdown-loader here */
            }
          }
        ]
      }
    ]
  }
}

Examinons ce que fait cette configuration :

Le tableau rules de la configuration Webpack définit un ensemble de tests du chemin d’accès au fichier, ainsi que les chargeurs qui doivent être utilisés lorsqu’une ressource correspondant au test est trouvée. Dans le cas présent, la propriété test vérifie la présence de chemins d’accès de fichiers se terminant par .md.
Le tableau use décrit une liste de chargeurs appliqués de façon séquentielle à la ressource. Ils sont appliqués du dernier au premier. Dans le cas présent, le premier chargeur à être appliqué est markdown-loader et le dernier est html-loader.
Lorsque plusieurs chargeurs sont spécifiés, le résultat de chaque chargeur est transmis au suivant.

Nous utiliserons ces informations pour le configurer dans notre projet.

Pour ajouter ce chargeur personnalisé à la configuration Webpack dans SharePoint Framework, nous devons indiquer à la tâche de génération de configurer Webpack. Les tâches de génération sont définies dans le fichier gulpfile.js, qui se trouve à la racine de votre projet.

Modifiez la valeur gulpfile.js et ajoutez le code suivant juste avant build.initialize(gulp); :

build.configureWebpack.mergeConfig({
  additionalConfiguration: (generatedConfiguration) => {
    generatedConfiguration.module.rules.push(
      {
        test: /\.md$/,
        use: [
          {
            loader: 'html-loader'
          },
          {
            loader: 'markdown-loader'
          }
        ]
      }
    );

    return generatedConfiguration;
  }
});

Nous allons étudier ce que fait cet extrait de code :

ConfigureWebpackTask (instancié comme build.configureWebpack) configure Webpack pour nous. Il existe de nombreuses configurations spéciales qui se produisent pour générer des projets SPFx ; la logique de cette tâche est donc importante.
ConfigureWebpackTask prend une propriété additionalConfiguration facultative. Nous voulons définir cette propriété sur une fonction qui prend la configuration générée, y apporte nos modifications, puis renvoie la configuration mise à jour. Cette fonction doit renvoyer une configuration Webpack à la chaîne d’outils, sinon Webpack ne sera pas configuré correctement.
Dans le corps de la fonction que nous avons définie sur additionalConfiguration, placez simplement une nouvelle règle sur l’ensemble des règles existantes dans la configuration. Notez que cette nouvelle règle est semblable à l’exemple dans l’extrait de code de configuration en haut de l’étape 2.

Remarque

Bien que vous puissiez remplacer complètement la configuration Webpack par défaut de la chaîne d’outils à l’aide de cette méthode, ceci n’est pas recommandé si vous souhaitez bénéficier de performances et d’un fonctionnement optimaux, sauf indication contraire dans la documentation.

Étape 3 : mettre à jour votre code

Maintenant que nous avons configuré le chargeur, nous allons mettre à jour notre code et ajouter quelques fichiers pour tester le scénario.

Créez un fichier ./src/my-markdown.md incluant un texte Markdown.

#Hello Markdown

*Markdown* is a simple markup format to write content.

You can also format text as **bold** or *italics* or ***bold italics***

Lorsque vous générez le projet, le chargeur Webpack markdown-loader convertit ce texte en une chaîne au format HTML.

Pour utiliser cette chaîne HTML dans vos fichiers source .ts*, ajoutez la ligne require() suivante en haut du fichier, après vos instructions import, par exemple :
```
const markdownString: string = require<string>('./../../../../src/my-markdown.md');
```
Par défaut, Webpack cherche le fichier dans le dossier lib, mais les fichiers .md ne sont pas copiés dans ce même dossier lib, ce qui signifie que nous devons créer un chemin d’accès relatif assez long. Nous pouvons contrôler ce paramètre en définissant un fichier de configuration qui indique à la chaîne d’outils de copier les fichiers md vers le dossier lib.
Créez un fichier ./config/copy-static-assets.json pour indiquer au système de génération de copier des fichiers supplémentaires de src vers lib. Cette tâche de génération copie les fichiers dont les extensions sont comprises par la configuration Webpack par défaut de la chaîne d’outils (telles que png et json), de sorte que nous devons simplement lui demander de copier aussi les fichiers md.
```
{
  "includeExtensions": [
    "md"
  ]
}
```
Au lieu d’utiliser le chemin d’accès relatif, vous pouvez désormais utiliser le chemin d’accès du fichier dans votre instruction require, par exemple :
```
const markdownString: string = require<string>('./../../readme.md');
```
Vous pouvez ensuite spécifier cette chaîne dans votre code, par exemple :
```
public render(): void {
  this.domElement.innerHTML = markdownString;
}
```

Étape 4 : générer et tester votre code

Pour générer et tester votre code, exécutez la commande suivante dans une console à la racine du répertoire de votre projet :

gulp serve

Voir aussi

Présentation de SharePoint Framework