SharePoint Framework (SPfx) : getting started and Deep Dive (Partie 2/3)

Bonnes pratiques et optimisations SPfx, intégrer Office Fabric UI et les tests unitaires

Dans cet article nous allons présenter comment bien développer des composants SharePoint via SharePoint Framework (SPfx) en mettant en évidence la mise en oeuvre des recommandations Microsoft et des bonnes pratiques.

Dans l’article précédent, je vous ai présenté l’historique concernant les évolutions de la plateforme SharePoint / Office 365 afin que vous puissiez avoir une vision globale de la plateforme.

• Partie 1 : SharePoint Sites modernes et la nouvelle expérience utilisateur !
• Partie 2 : Bonnes pratiques et optimisations SPfx, intégrer Office Fabric UI et les tests unitaires
• Partie 3 : SPfx et VSTS/DevOps pour l’intégration/livraison continue.

Le but de cette deuxième partie est de vous présenter les différents challenges auxquels on peut faire face une fois le développement terminé et que nos packages sont envoyés en production chez le client. C’est généralement lors de cette phase que l’on se rend compte que le comportement du composant (taille de package, temps de déploiement, temps de chargement et de réponse, etc.) est totalement différent de celui que l’on a développé dans un environnement de test/développement.

Toujours installer la dernière mise à jour du Framework SharePoint

Comme nous le savons, SPfx est en constante évolution et au cours de ce processus, certaines versions de Microsoft sont livrées avec des bugs potentiels qui peuvent causer des problèmes majeurs. Microsoft (communauté PnP) publie des correctifs rapidement et fréquemment. Il est important de rester à jour avec les derniers paquets SPfx.

Un bon exemple de ceci est la version 1.4 qui a contenu un bug majeur sur les WebParts qui ne s’installaient pas dans les sous-sites. Microsoft a publié la version 1.4.1 pour pallier à ce problème.

💡 Si vous ne gardez pas un œil sur les dernières versions, vous finirez par brûler l’huile de minuit pour comprendre la cause de ces problèmes.

Identifier et supprimer les packages obsolètes

Alors, pour atteindre vos objectifs, vous devez exécuter la commande : ‘npm outdated‘. Ainsi, vous trouverez tous les paquets ou extensions obsolètes. Vous devez aussi vous assurer que vous avez un plan pour remplacer ces paquets obsolètes.

Synchroniser la version du projet global avec la version du composant SharePoint

En fait, tout projet SharePoint Framework comporte deux types de versions différentes :

• Le numéro de version plus orienté projet est stocké dans le ‘package.json‘.
• Le composant WebPart associé est stocké dans le fichier ‘package-solution.json‘ dans le dossier config.

Les deux sont des versions valides de votre projet, mais elles ne sont pas synchronisées et doivent être mises à jour individuellement. Pour SharePoint, vous pouvez mettre à jour le fichier package-solution. Pour le projet global, vous mettez à jour ‘package.json‘ dans le dossier racine.

💡 Si vous ne préservez pas du temps pour concevoir une stratégie de versioning, vous perdrez la trace de vos versions et il sera alors difficile de décider laquelle est la bonne.

Utiliser la bibliothèque Pnp Js

La nouvelle bibliothèque de base JavaScript a été créé pour aider les développeurs et ce, en simplifiant les opérations courantes dans SharePoint. Actuellement, la bibliothèque contient une API fluide pour envelopper l’API REST SharePoint quasi complète ainsi que des fonctions utilitaires et auxiliaires.

💡 Nous pouvons les utiliser avec SharePoint Framework pour travailler avec SharePoint en un minimum d’effort.

❕ FUTURE DE LA BIBLIOTHEQUE SP-PNP-JS

La nouveauté pour sp-pnp-js est que la communauté Microsoft a décidé d’arrêter de fournir le “framework” en un seul module (package) unique mais plutôt de le fournir en plusieurs sous-modules (mini-bibliothèques). Cela offre aux développeurs plus de souplesse pour maîtriser les parties qu’ils souhaitent intégrer en réduisant la taille du projet.

L’équipe SharePoint Patterns and Practices confirme que la bibliothèque ne cesse de grandir, d’où l’intérêt d’organiser en plusieurs fichiers *.js.

💡 A partir de Juillet 2018, l’équipe PnP ne supporte que les sous mini-bibliothèques définies par @pnp. En revanche, l’ancienne bibliothèque sp-pnp-js restera sur npm (Node Package Manager) afin que vous puissiez continuer à l’utiliser pour les projets existants, et le projet restera comme une référence sur Git.

💡 Aucun projet existant référençant l’ancienne bibliothèque ne sera endommagé par ce déménagement.

Pour plus d’informations sur la nouvelle approche PnP JS je vous mets à disposition deux liens utiles (Github et Guide nouvelle Bibliothèque).

La bonne gestion des dépendances des bibliothèques installées

💡 Il est nécessaire de s’assurer que vous utilisez l’option –save ou –save-exact lors de l’ajout de bibliothèques en lançant npm install (ceci afin qu’elles puissent être enregistrées dans votre fichier package.json et que les autres développeurs de l’équipe puissent construire avec succès à partir du contrôle source).

💡 La nécessité d’exécuter npm shrinkwrap pour chaque version de votre code permet de geler les versions des bibliothèques référencées et de garantir qu’il n’y aura pas des régressions.

Note : si vous avez la version npm 5.X dans votre PC, vous pouvez ignorer les préconisations ci-dessus, cette version effectue automatiquement une sauvegarde (–save) lors d’une installation, et génère automatiquement un fichier package-lock.json (similaire à npm-shrinkwrap.json).

Bien intégrer Office UI Fabric React

La bibliothèque Office UI Fabric n’intègre pas uniquement des styles, elle contient également des contrôles (composants) que vous pouvez réutiliser dans d’autres applications. Ce que l’équipe OneDrive Design Studio a décidé de faire, c’est d’utiliser le framework ReactJS pour créer ces contrôles et les fournir dans une bibliothèque nommée UI Fabric React.

Microsoft recommande d’installer la dernière version du package UI Fabric React et de placer une dépendance explicite sur cette version spécifique dans le package.json du projet.

Lorsque vous utilisez les composants Fabric React, vous devez généralement veiller à utiliser une liaison statique dans vos instructions d’importation (afin de réduire la taille du package final), par exemple :

// correct - static linking.
import { Button } from 'office-ui-fabric-react/lib/Button';

// incorrect - dynamic linking.
import { Button } from '@microsoft-ui-fabric-react';

render() {
    ...

<div>
    <Button>click me</Button>
</div>

    ...
}

Note : les versions 2.x ou antérieures de UI Fabric React ne sont pas prises en charge dans SharePoint Framework.

Le package office-ui-fabric-react inclut les styles Fabric Core pris en charge dans les composants Fabric React. Je vous recommande d’importer les styles Fabric Core à partir du package office-ui-fabric-react au lieu du package @microsoft/sp-office-ui-fabric-core pour vous assurer que les bons styles soient utilisés dans votre composant.

Comme le module @microsoft/sp-office-ui-fabric-core est déjà installé dans votre solution par le générateur Yeoman, je vous recommande de désinstaller ce module si vous décidez d’utiliser des composants UI Fabric et de réduire la taille de votre bundle.

Vous pouvez ensuite importer les styles principaux à partir des déclarations Sass disponibles dans le package office-ui-fabric-react.

Déploiement : optimiser les builds pour la production

Gardez en tête que toutes les bibliothèques tierces qu’on ajoute dans le projet vont être regroupées dans votre composant WebPart à la compilation. Cela augmente la taille du bundle (package) et peut poser des problèmes de performance si l’on a plusieurs composants WebPart/Extensions qui référencent la même bibliothèque (Office UI Fabric peut être un grand coupable dans ce cas !).

💡 Ne pas inclure les bibliothèques tierces dans le bundle : en effet, lorsque l’on référence des bibliothèques tierces dans un projet, SharePoint Framework les inclut dans le bundle généré à la compilation. Par conséquent, les utilisateurs travaillant avec notre solution finissent par télécharger la même bibliothèque plusieurs fois, une fois pour chaque composant. La taille totale de la page augmente de manière significative, ce qui prend plus de temps à charger et conduit à une mauvaise expérience utilisateur, d’autant plus si le réseau est lent.

💡Penser au CDN Office 365/Azure : si vous travaillez avec des bibliothèques tierces, vous devez toujours envisager de les charger depuis un emplacement externe : soit un CDN public, soit un emplacement d’hébergement appartenant à votre organisation. Cela permet d’exclure la bibliothèque du bundle, ce qui réduit énormément sa taille.

💡 Vérifier le contenu du bundle : pour mieux comprendre la taille des ensembles générés, vous pouvez étendre la configuration de Webpack dans le projet et faire en sorte que SharePoint Framework génère des statistiques de regroupement. Pour atteindre notre objectif, il faut installer le paquet webpack-bundle-analyser dans le projet, en exécutant ce qui suit dans la ligne de commande :

Après, il faut changer le contenu du fichier gulpfile.js du projet :

'use strict';
 
const gulp = require('gulp');
const path = require('path');
const build = require('@microsoft/sp-build-web');
const bundleAnalyzer = require('webpack-bundle-analyzer');
 
build.configureWebpack.mergeConfig({
additionalConfiguration: (generatedConfiguration) => {
const lastDirName = path.basename(__dirname);
const dropPath = path.join(__dirname, 'temp', 'stats');
generatedConfiguration.plugins.push(new bundleAnalyzer.BundleAnalyzerPlugin({
openAnalyzer: false,
analyzerMode: 'static',
reportFilename: path.join(dropPath, `${lastDirName}.stats.html`),
generateStatsFile: true,
statsFilename: path.join(dropPath, `${lastDirName}.stats.json`),
logLevel: 'error'
}));
 
return generatedConfiguration;
}
});
 
build.initialize(gulp);

Dès qu’on lance la commande gulp bundle, un dossier temp/stats va être rajouté dans le projet. L’un des fichiers de statistiques généré est un treemap montrant les différents scripts inclus dans le bundle généré. Vous pouvez trouver cette visualisation dans le fichier ./temp/stats/[solution-name].stats.html.

Écrire des tests unitaires pour vos composants SharePoint Framework

Maintenant, lorsque l’on code avec React nos composants, il est plus judicieux de faire des tests intensifs sur les composants eux-mêmes. Cela donne plus de contrôle sur les tests de composants et les résultats que vous voulez tester. Par exemple, on peut changer l’état, déclencher l’appel aux fonctions et aussi simuler les événements de clic et bien d’autres choses encore !

Lorsque l’on crée un nouveau projet SPfx, Yeoman va créer automatiquement un dossier de test sous le dossier du composant WebPart :

Dans le dossier, vous trouverez un exemple de fichier de test : <nom_WebPart> .test.ts.

💡 La première chose à faire si on veut tester les composants est de changer l’extension ts (typescript) en tsx (typescript pour JSX ). Cela vous permet de charger les composants dans la syntaxe JSX.

💡 Une fois qu’on a modifié l’extension du fichier de test, on doit installer les dépendances développeur supplémentaires suivantes :

• enzyme: https://github.com/airbnb/enzyme
  
• enzyme-adapter-react-15
• react-test-renderer
• react-addons-test-utils: https://facebook.github.io/react/docs/test-utils.html

Enzyme

C’est un ensemble d’utilitaires de tests créé pour React (développé par Airbnb) et qui nécessite l’utilitaire react-addons-test-utils. Enzyme facilite l’affirmation (Assert) et manipule les sorties des composants.

Pour installer ces deux dépendances, exécutez la commande suivante : npm install enzyme react-addons-test-utils enzyme-adapter-react-15 react-test-renderer –save-dev –save-exact

On est prêt maintenant à écrire quelques tests. Commençons par écrire notre premier test comme suit :

Le code que vous voyez ci-dessus ne contient aucun test pour le moment. La fonction before est la première qui est appelée et charge le composant et à la fin des tests, la fonction after restaure tous les composants.

Vous pouvez également faire quelque chose avant et après chaque test en écrivant les fonctions beforeEach et afterEach.

Maintenant, pour écrire les tests, on va appeler la fonction it(‘Message pour le test’, callbackfn), comme suit :

Pour lancer les tests, on doit exécuter cette commande : gulp test. Dès qu’on lance la commande de test, on aura dans la console un résultat qui ressemble à cela :

Enfin, vous trouverez un lien vers un exemple de projet sur GitHub qui montre comment vous pouvez tester vos composants SharePoint Framework avec des tests unitaires prédéfinis.

Conclusion

Dans cet article, j’ai essayé de valoriser les bonnes pratiques de développement SharePoint Framework, de présenter également la manière d’éviter les impacts négatifs auxquels on peut faire face en utilisant Microsoft Office UI Fabric, d’optimiser nos packages avant l’installation en production et on a fini avec les tests unitaires pour montrer comment intégrer les tests dans un projet SPfx d’une manière simple.

Restez à l’écoute pour la prochaine et dernière partie de cette suite qui va traiter de l’intégration continue, de DevOps et de tout ce qu’il vous faut pour automatiser l’intégration de vos composants sur les environnements de vos clients 🙂