Blue Valet - Bibliothèque de composants

Application "react-syileguidist", comprenant l'ensemble des composants communs des différentes applications Blue Valet

Utilisation

Installez le module avec la commande suivante :

$ npm install bv-common-ui

Importez le CSS dans votre application

import 'bv-common-ui/dist/index.css;

Pour importer un composant :

import { Input, Button } from 'bv-common-ui';

Installation

Commencez par cloner le projet

// HTTPS
$ git clone https://gitlab.com/blue-valet/common-ui.git

// SSH
$ git clone [email protected]:blue-valet/common-ui.git

$ cd common-ui

Installez toutes les dépendances nécessaires

$ npm install

Vue globale de l'application

Scripts

Voici la liste des différents scripts et leur utilité :

• "start": "concurrently \"npm:watch-css\" \"npm:styleguide\""

  Démarre le serveur de développement en lançant en parallèle "watch-css" et "styleguide".

• "build-css": "node-sass --include-path scss src/styles/index.scss dist/index.css"

  Compile tous les scss dans le fichier dist/index.css.

• "watch-css": "npx nodemon -e scss -x \"npm run build-css\""

  Surveille chaque changement dans le scss et re-compiler automatiquement tout le style. Cette compilation est nécessaire afin de pouvoir recharger automatiquement "styleguide" et ainsi profiter d'un développement en mode live.

• "styleguide": "npx styleguidist server"

  Lance le serveur "styleguidist" sur le port 6060

• "build": "cp -R src/styles/fonts/* dist/fonts && rollup -c"

  Compile l'ensemble des composants ainsi que leur style, pour une mise en production du module.

• "lint-all": "eslint src --ext js,jsx"

  Lance eslint sur l'ensemble des fichiers js et jsx.

• "lint-jsx": "eslint src/**/*.jsx"

  Lance eslint uniquement sur les fichiers jsx.

Dossiers et fichiers

• Les composants React se trouvent dans le dossier src/components

• Les styles se trouvent dans le dossier src/styles

• La liste des composants qui doivent être exportés par le module se trouvent dans le fichier src/exports.js

• Tous les assets et les composants exportés se trouvent dans le dossier dist/

Mode développement

Une fois toutes les dépendances installées, il suffit de lancer la commande suivante pour démarrer le serveur en mode "dev"

$ npm start

Ajout d'un composant

Pour ajouter un nouveau composant, suivez les étapes suivantes :

0. Créez une nouvelle branche à partir de master à jour

   $ git checkout master
   $ git pull
   $ git checkout -b <ma nouvelle branche>

1. Si le composant n'est pas dans une des sections déjà présentes (buttons, forms, ...) commencez par ajouter la section :

   • Ouvrez le fichier styleguide.config.js
   • Ajoutez votre section dans la partie "sections"
   • Il faut au moins le nom de la section ainsi que le le chemin vers les nouveaux composants qui vont être créés (pour plus d'informations sur les différents paramètres, voir la doc officielle des sections)

2. Créez le nouveau dossier dans src/components

3. Créez maintenant tous vos composants React (en suivant les règles de bonnes pratiques déjà présentes)

   • Ajoutez et documentez les "propTypes" et les "defaultProps" pour générer automatiquement la documentation
   • Une fois le composant à minima "construit" (c'est à dire au moins un render fonctionnel) vous pouvez (re)démarrer le serveur de développement pour voir l'évolution du composant "en temps réel"

4. Créez les différents styles associés à ce composant

   Ne pas oublier d'ajouter l'import du nouveau src/styles/<nom du composant>.scss dans le fichier src/styles/index.scss

5. Créez le fichier <nom du composant>.md avec différents exemples

6. Une fois le composant terminé, ajoutez son export dans le fichier src/exports.js

Modification d'un composant

Pour modifier un compsant, rien de plus simple :

1. Modifez le composant
2. Mettez à jour la documentation si des informations ont changés (nouvelles props, nouveau comportement, ...)
3. Mettez à jour les exemples dans le fichier <nom du composant>.md correspondant

Suppression d'un composant

Pour supprimer un composant, suivez les étapes suivantes :

1. Supprimez le composant ainsi que sa doc <nom du composant>.md correspondante
2. Supprimez tous les styles associés ainsi que les imports dans src/styles/<nom du composant>.scss
3. Supprimez l'export du composant dans src/exports.js
4. Si c'est le dernier composant d'une section, supprimez le dossier ainsi que sa section associée dans le fichier styleguide.config.js

Publier le module

Une fois tous les ajouts/modifications effectué(e)s, il faut maintenant publier une nouvelle version du projet.

Commencez par mettez à jour le dépôt distant :

$ git add <les fichiers correspondants>
$ git commit -m "message explicite"
$ git push origin <nom de ma branche>

Vérifiez sur le serveur que tout est au vert, et effectuez une Merge Request sur master.

Ensuite, mettez à jour le nouveau type de version (major, minor, patch) Pour plus d'informations, voir la documentation NPM

$ git checkout master
$ git pull
$ npm version < version | major | minor | patch > -m "Upgrade to %s"

Une fois la version mise à jour, le dépôt va automatiquement lancer le déploiement.