Message original en russe
Garder votre code cohĂ©rent et bien formatĂ© n'est pas une tĂąche facile, mĂȘme lorsque vous travaillez seul. Mais lorsque vous travaillez avec une Ă©quipe ou avec un projet open source, tout devient encore plus difficile. Chacun a son propre style de code, quelqu'un n'exĂ©cute pas de tests et personne n'Ă©crit de documentation. Cet article vous aidera Ă configurer toutes ces choses et bien plus encore - automatisez cette routine pour ne jamais le faire manuellement.
AprĂšs avoir lu, vous obtiendrez votre propre projet prĂȘt pour npm avec les fonctionnalitĂ©s suivantes:
- Formatage du texte et style de code
- Tests automatisés avec couverture de code et seuil
- Style de validation unifié
- Documentation générée à partir du code et valide
- Processus de publication automatisé
C'est parti!
Prérequis
Créez un nouveau dossier, initialisez un nouveau référentiel, projetez et passez à l'étape suivante.
git init npm init npm i -D typescript ./node_modules/.bin/tsc --init
Commençons par la mise en forme du code - types d'indentation, taille, etc. Le premier outil est le fichier .editorconfig . Il ne nécessite rien d'autre que vous IDE et aide à garder votre mise en forme automatique cohérente dans toute votre équipe.
Créez .editorconfig à la racine du projet avec le contenu suivant (n'hésitez pas à le changer pour votre style souhaité)
#root = true [*] indent_style = space end_of_line = lf charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true max_line_length = 100 indent_size = 4 [*.md] trim_trailing_whitespace = false
C'est vraiment génial, mais parfois il n'a pas assez de puissance pour répondre à vos besoins. Pour vous assurer que tout est bien formaté, plus joli apparaßt. Si vous oubliez de formater le code, plus joli le fera pour vous.
npm i -D prettier
Ajoutez cette commande Ă la section des scripts de votre fichier package.json
"prettier": "prettier --config .prettierrc.json --write src/**/*.ts"
Et ajoutez le fichier .prettierrc.json avec vos paramĂštres Ă la racine du projet
{ "tabWidth": 4, "useTabs": false, "semi": true, "singleQuote": true, "trailingComma": "es5", "arrowParens": "always" }
Vous pouvez maintenant écrire du code et essayer d'exécuter "npm run prettier". Prettier vérifiera le dossier src et formatera automatiquement votre code sans aucune aide de votre part!
Style de code
Style de code - comme Ă©viter d'utiliser == au lieu de === ou l'observation des variables doit Ă©galement ĂȘtre vĂ©rifiĂ©e. A cet effet, nous prendrons tslint . Si vous prĂ©fĂ©rez javascript - prenez plutĂŽt eslint .
npm i -D tslint ./node_modules/.bin/tslint --init
La derniÚre commande créera un fichier tslint.json pour vous. Il conserve vos paramÚtres et étend déjà tslint: ensemble de rÚgles recommandé, mais vous pouvez les étendre ou les remplacer comme vous le souhaitez. N'oubliez pas d'ajouter la commande lint à votre package.json.
package.json
"lint": "tslint -c tslint.json 'src/**/*.ts' 'tests/**/*.spec.ts'"
Comme vous le voyez, la configuration fonctionne avec src et le dossier tests, donc tout votre code doit y ĂȘtre placĂ©.
Test
Il est maintenant temps de mettre en place nos tests. Installer le karma et d'autres dépendances connexes
npm i -D karma karma-jasmine jasmine karma-typescript karma-chrome-launcher @types/jasmine ./node_modules/.bin/karma init
Et ajoutez un nouveau bloc de configuration au karma.conf.js nouvellement créé
karma.conf.js karmaTypescriptConfig : { include: ["./src/**/*.ts", "./tests/**/*.spec.ts"], tsconfig: "./tsconfig.json", reports: { "html": "coverage", "lcovonly": { directory: './coverage', filename: '../lcov.dat' } }, coverageOptions: { threshold: { global: { statements: 60, branches: 60, functions: 60, lines: 60 }, file: { statements: 60, branches: 60, functions: 60, lines: 60, } } }, }
Cela configurera le fichier de couverture de code et le niveau de seuil. Les deux sont importants. Le premier vous aide à gérer votre couverture et le second maintient votre couverture à un certain niveau.
Mettre Ă jour package.json
"test": "karma start"
Et essayez de l'exécuter. N'oubliez pas d'écrire du code dans le dossier src et des tests dans le dossier tests. Voici à quoi ressemblera votre rapport de couverture de code:
Btw, si vous prévoyez d'utiliser l'intégration continue (comme Travis, Jenkins ou ainsi de suite), il est préférable de changer Chrome runner en HeadlessChrome avec marionnettiste . Pour plus d'informations sur HeadlessChrome et CI - consultez mon référentiel de démonstration sur GitHub.
Style de validation
Habituellement, toutes les écritures sont validées dans un format "aléatoire". Donc, pour que les commits soient suffisamment bons, le commitizen a été inventé. Cet outil pose quelques questions et génÚre un commit pour vous. Un autre bon point que nous pouvons générer un fichier journal des modifications à partir de commits écrits avec l'aide de commitizen.
Installer l'adaptateur commitizen et conventionnel-changelog
npm i -D commitizen npm i -D cz-conventional-changelog
Mettre Ă jour les scripts
"commit":"git-cz"
Ajoutez une nouvelle section de configuration dans package.json pour commitizen.
"config": { "commitizen": { "path": "./node_modules/cz-conventional-changelog" } }
Essayez de faire un commit ou vérifiez cette image pour avoir une idée de son apparence:
La documentation
Si votre projet est plus grand que quelques fonctions, c'est une bonne idée d'avoir de la documentation. Et c'est encore mieux lorsque vous n'avez pas besoin d'écrire quelque chose manuellement. à cette fin, une typedoc existe. Il prend vos fichiers .ts, vos commentaires jsdoc et crée une documentation agréable et brillante. Si vous utilisez JavaScript - vous pouvez essayer esdoc à la place.
Voici un exemple, comment typedoc a décrit ma fonction isNumberStrict:
npm i -D typedoc
package.json
"doc": "typedoc --out docs/src"
Une autre bonne idée est de générer automatiquement votre fichier journal des modifications. Comme je l'ai mentionné précédemment, commitizen prend en charge le journal des modifications conventionnel. Ainsi, nous pouvons prendre des validations et les convertir dans le fichier journal des modifications.
Installer convention-changelog-cli
npm i -D conventional-changelog-cli
Et mettez Ă jour package.json avec la nouvelle commande
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
Ne vous inquiétez pas, angulaire signifie uniquement la mise en forme du style et rien de plus. Maintenant, votre changelog sera formé comme ci-dessous:
Construire
La construction est assez simple et il suffit d'ajouter des commandes de construction et de nettoyage au package.json
"clean":"rmdir dist /S /Q", "build": "tsc --p ./ --sourceMap false",
Si vous avez besoin de regroupement ou de minification - essayez uglifyjs .
Automatisation
Ok, la plupart ont déjà été faites. Nous avons créé un tas de scripts différents pour garder notre code propre et correct. Mais les exécuter manuellement à chaque fois est une tùche assez ennuyeuse et peut conduire à des erreurs. Nous devons donc les automatiser. Comme vous le savez, lorsque vous faites un commit, quelques événements git apparaissent - pré-commit, post-commit et ainsi de suite. Nous pouvons les utiliser pour exécuter nos propres scripts avant que le code ne soit validé ou poussé. Mais il y a un problÚme - les crochets git ne sont pas partageables. Et c'est pourquoi Husky apparaßt. Ce package encapsule les événements git et exécute vos scripts à partir de package.json. Si le script échoue, la validation sera annulée et vous recevrez le message indiquant ce qui ne va pas.
Installer husky
npm i -D husky
Et décrivez quelques crochets à l'intérieur de package.json
"precommit":"npm run prettier", "prepush": "call npm run lint && call npm run test"
Maintenant, lorsque vous essayez de rendre une validation plus jolie, elle s'exécute et corrige tous les problÚmes de formatage. Lorsque vous essayez de créer un style push-code, les tests seront effectués automatiquement. Vous pouvez étendre ces commandes tout ce dont vous avez besoin, comme l'envoi de notifications, une vérification supplémentaire, etc.
Publier
GĂ©nial, nous avons presque fini. Supposons donc que nous soyons prĂȘts Ă publier le package sur npm. Comme vous le savez, beaucoup de travail doit ĂȘtre fait avant - tests, mise Ă jour de la documentation, version et mise Ă jour des balises. Facile d'oublier quelque chose, oui? C'est donc une bonne idĂ©e d'automatiser Ă©galement ce processus. Ă cette fin, nous utiliserons des hooks npm natifs - prĂ©version, version et postversion. Ajoutez les lignes suivantes Ă la section des scripts de votre package.json
"preversion": "npm run test", "version": "call npm run clean && call npm run build && call npm run doc && call npm run changelog && git add . && git commit -m 'changelogupdate' --no-verify", "postversion": "git add . && git push && git push --tags"
Lorsque vous exécuterez la commande npm version, le script de préversion exécutera des tests, le script de version construira votre code et générera tous les documents. Ensuite, la version sera augmentée, puis tout sera validé et repoussé. Maintenant, tout ce dont vous avez besoin est d'exécuter la commande npm publish et c'est tout. Juste aux commandes et tout le reste sera fait sans aucun effort de votre part.
Enfin, nous devons spécifier les dossiers à inclure dans le projet et l'emplacement du point d'entrée. Mettre à jour package.json la derniÚre fois
"main": "./dist/index.min.js", "types": "./dist/index.d.ts", "files": [ "dist/", "src/", "tests/" ]
C'est tout, votre projet gĂ©nial est prĂȘt Ă dĂ©marrer!
Liens utiles
Merci d'avoir lu. Si vous avez des questions, veuillez consulter mon référentiel de démonstration ici ou demander dans les commentaires.
Passez une bonne journée!