Ursprünglicher Beitrag in russischer Sprache
Es ist keine leichte Aufgabe, Ihren Code konsistent und gut formatiert zu halten, selbst wenn Sie alleine arbeiten. Wenn Sie jedoch mit einem Team oder einem Open Source-Projekt arbeiten, wird alles noch schwieriger. Jeder hat seinen eigenen Codestil, jemand führt keine Tests durch und niemand schreibt Dokumentation. Dieser Artikel hilft Ihnen dabei, all diese Dinge einzurichten und noch mehr - automatisieren Sie diese Routine, um sie niemals manuell auszuführen.
Nach dem Lesen erhalten Sie Ihr eigenes npm-fähiges Projekt mit den nächsten Funktionen:
- Textformatierung und Codestil
- Automatisierte Tests mit Codeabdeckung und Schwellenwert
- Einheitlicher Festschreibungsstil
- Aus dem Code generierte Dokumentation und Commits
- Automatisierter Veröffentlichungsprozess
Lass uns gehen!
Voraussetzungen
Erstellen Sie einen neuen Ordner, initialisieren Sie ein neues Repository, projizieren Sie und fahren Sie mit dem nächsten Schritt fort.
git init npm init npm i -D typescript ./node_modules/.bin/tsc --init
Beginnen wir mit der Code-Formatierung - Einrückungstypen, Größe usw. Das erste Tool ist die Datei .editorconfig . Es erfordert nichts außer Ihrer IDE und hilft dabei, Ihre automatische Formatierung im gesamten Team konsistent zu halten.
Erstellen Sie .editorconfig im Stammverzeichnis des Projekts mit dem nächsten Inhalt (Sie können ihn jederzeit an den gewünschten Stil anpassen).
#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
Das ist wirklich großartig, aber manchmal hat es nicht genug Leistung, um Ihre Bedürfnisse zu erfüllen. Um sicherzustellen, dass alles gut formatiert ist, erscheint hübscher . Wenn Sie vergessen, den Code zu formatieren, erledigt Prettier dies für Sie.
npm i -D prettier
Fügen Sie diesen Befehl dem Skriptabschnitt Ihrer Datei package.json hinzu
"prettier": "prettier --config .prettierrc.json --write src/**/*.ts"
Fügen Sie die Datei .prettierrc.json mit Ihren Einstellungen zum Stammverzeichnis des Projekts hinzu
{ "tabWidth": 4, "useTabs": false, "semi": true, "singleQuote": true, "trailingComma": "es5", "arrowParens": "always" }
Jetzt können Sie Code schreiben und versuchen, "npm run prettier" auszuführen. Prettier überprüft den src-Ordner und formatiert Ihren Code automatisch ohne Hilfe von Ihrer Seite!
Codestil
Der Codestil - wie das Vermeiden der Verwendung von == anstelle von === oder das Abschatten von Variablen - muss ebenfalls überprüft werden. Zu diesem Zweck werden wir tslint nehmen. Wenn Sie Javascript bevorzugen, nehmen Sie stattdessen eslint .
npm i -D tslint ./node_modules/.bin/tslint --init
Mit dem letzten Befehl wird die Datei tslint.json für Sie erstellt. Es behält Ihre Einstellungen bei und erweitert bereits tslint: empfohlene Regeln, aber Sie können sie erweitern oder überschreiben, was immer Sie wollen. Vergessen Sie nicht, Ihrem package.json den Befehl lint hinzuzufügen.
package.json
"lint": "tslint -c tslint.json 'src/**/*.ts' 'tests/**/*.spec.ts'"
Wie Sie sehen, ist es so eingerichtet, dass es mit dem Ordner src und tests funktioniert. Daher sollte Ihr gesamter Code dort abgelegt werden.
Testen
Jetzt ist es Zeit, unsere Tests einzurichten. Installieren Sie Karma und andere verwandte Abhängigkeiten
npm i -D karma karma-jasmine jasmine karma-typescript karma-chrome-launcher @types/jasmine ./node_modules/.bin/karma init
Und fügen Sie neu erstellten karma.conf.js einen neuen Konfigurationsblock hinzu
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, } } }, }
Dadurch werden die Codeabdeckungsdatei und der Schwellenwert festgelegt. Beides ist wichtig. Das erste hilft Ihnen, mit Ihrer Deckung umzugehen, und das zweite hält Ihre Deckung auf einem bestimmten Niveau.
Aktualisieren Sie package.json
"test": "karma start"
Und versuchen Sie es auszuführen. Vergessen Sie nicht, Code in den Ordner src und Tests in den Ordner tests zu schreiben. So sieht Ihr Code-Coverage-Bericht aus:
Übrigens, wenn Sie eine kontinuierliche Integration planen (wie Travis, Jenkins usw.), ist es besser, Chrome Runner mit Puppenspieler auf HeadlessChrome zu ändern. Weitere Informationen zu HeadlessChrome und CI finden Sie in meinem Demo- Repository auf GitHub.
Commit-Stil
Normalerweise werden alle Schreibvorgänge in einem "zufälligen" Format ausgeführt. Um die Commits gut genug zu halten, wurde der Commitizen erfunden. Dieses Tool wirft einige Fragen auf und generiert ein Commit für Sie. Ein weiterer guter Punkt, den wir aus Commits generieren können, die mit Hilfe von Commitizen geschrieben wurden.
Installieren Sie den Commitizen- und den konventionellen Changelog-Adapter
npm i -D commitizen npm i -D cz-conventional-changelog
Skripte aktualisieren
"commit":"git-cz"
Fügen Sie einen neuen Konfigurationsabschnitt in package.json für Commitizen hinzu.
"config": { "commitizen": { "path": "./node_modules/cz-conventional-changelog" } }
Versuchen Sie, ein Commit durchzuführen, oder überprüfen Sie dieses Bild, um eine Vorstellung davon zu erhalten, wie es aussehen wird:
Dokumentation
Wenn Ihr Projekt größer als einige Funktionen ist, ist es eine gute Idee, eine Dokumentation zu haben. Und es ist noch besser, wenn Sie etwas nicht manuell schreiben müssen. Zu diesem Zweck existiert typedoc . Es nimmt Ihre .ts-Dateien, Ihre jsdoc-Kommentare und erstellt eine schöne und glänzende Dokumentation. Wenn Sie JavaScript verwenden, können Sie stattdessen esdoc ausprobieren.
Hier ist ein Beispiel, wie typedoc meine Funktion isNumberStrict beschrieben hat:
npm i -D typedoc
package.json
"doc": "typedoc --out docs/src"
Eine weitere gute Idee ist es, Ihre Änderungsprotokolldatei auch automatisch zu generieren. Wie ich bereits erwähnt habe, unterstützt Commitizen das konventionelle Changelog. Wir können also Commits annehmen und sie in die Änderungsprotokolldatei konvertieren.
Installieren Sie konventionelle Changelog-Cli
npm i -D conventional-changelog-cli
Und aktualisieren Sie package.json mit dem neuen Befehl
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
Keine Sorge, eckig bedeutet nur Stilformatierung und nichts weiter. Jetzt wird Ihr Changelog wie folgt erstellt:
Bauen
Der Build ist recht einfach und es ist nur eine Frage des Hinzufügens von Build- und Clean-Befehlen zur package.json
"clean":"rmdir dist /S /Q", "build": "tsc --p ./ --sourceMap false",
Wenn Sie eine Bündelung oder Minimierung benötigen, versuchen Sie es mit uglifyjs .
Automatisierung
Ok, der größte Teil ist bereits erledigt. Wir haben eine Reihe verschiedener Skripte erstellt, um unseren Code sauber und korrekt zu halten. Aber jedes Mal manuell auszuführen ist eine ziemlich langweilige Aufgabe und kann zu Fehlern führen. Wir müssen sie also automatisieren. Wie Sie wissen, werden beim Festschreiben einige Git-Ereignisse angezeigt - Pre-Commit, Post-Commit und so weiter. Wir können sie verwenden, um unsere eigenen Skripte auszuführen, bevor der Code festgeschrieben oder gepusht wird. Aber es gibt ein Problem - Git-Hooks können nicht geteilt werden. Und deshalb erscheint Husky . Dieses Paket umschließt die Git-Ereignisse und führt Ihre Skripte von package.json aus. Wenn das Skript fehlschlägt, wird das Festschreiben abgebrochen und Sie erhalten die Meldung, was falsch läuft.
Installieren Sie Husky
npm i -D husky
Und beschreiben Sie einige Hooks in package.json
"precommit":"npm run prettier", "prepush": "call npm run lint && call npm run test"
Wenn Sie nun versuchen, ein Commit schöner zu gestalten, werden alle Formatierungsprobleme ausgeführt und behoben. Wenn Sie versuchen, einen Push-Code-Stil zu erstellen, werden die Tests automatisch durchgeführt. Sie können diese Befehle beliebig erweitern, z. B. Benachrichtigungen senden, zusätzliche Prüfungen durchführen usw.
Veröffentlichen
Großartig, wir sind fast fertig. Nehmen wir also an, wir sind bereit, das Paket auf npm zu veröffentlichen. Wie Sie wissen, sollte vor dem Testen von Tests, Dokumentationsaktualisierungen, Versionen und Tags noch viel Arbeit geleistet werden. Leicht etwas zu vergessen, ja? Daher ist es eine gute Idee, auch diesen Prozess zu automatisieren. Zu diesem Zweck verwenden wir native npm-Hooks - Preversion, Version und Postversion. Fügen Sie die nächsten Zeilen zum Skriptabschnitt Ihrer package.json hinzu
"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"
Wenn Sie den Befehl npm version ausführen, führt das Preversion-Skript Tests aus, das Versionsskript erstellt Ihren Code und generiert alle Dokumente. Dann wird die Version erhöht und dann werden alle festgeschrieben und herausgeschoben. Jetzt müssen Sie nur noch den Befehl npm Publish ausführen und das ist alles. Nur Befehle und alles andere wird ohne Anstrengung von Ihrer Seite erledigt.
Zuletzt müssen wir angeben, welche Ordner in das Projekt aufgenommen werden sollen und wo sich der Einstiegspunkt befinden kann. Aktualisieren Sie package.json beim letzten Mal
"main": "./dist/index.min.js", "types": "./dist/index.d.ts", "files": [ "dist/", "src/", "tests/" ]
Das ist alles, dein großartiges Projekt ist fertig!
Nützliche Links
Danke fürs Lesen. Wenn Sie Fragen haben, überprüfen Sie bitte mein Demo-Repository hier oder fragen Sie in Kommentaren.
Einen schönen Tag noch!