hornet-js-builder
Advanced tools
Builder/loader des Applications Hornet, Wrapper NPM permettant de fixer les versions des dépendances
hornet-js-builder a été développé dans le but premier de masquer la complexité des différentes tâches nécessaires à la construction d'un projet. Son second objectif est d'accompagner le développeur en lui fournissant des outils tout au long du developpement d'un projet.
A cet effet il surcharge les librairies gulp et npm pour fournir des tâches se rapprochant de la philosophie maven ainsi que des utilitaires pour simplifier et pérenniser la gestion des dépendances.
Les versions de chaque dépendance déclarée doivent également être fixes (sans ^, ~ ou *) afin de pérenniser les versions.
$ npm install -g hornet-js-builder
Installer hornet-js-builder de manière globale:
$ npm install -g
En cas de MAJ à partir d'une version antérieure de hornet-js-builder: supprimer les dossiers node_modules de chaque projet
Suite à cette installation, les commandes hornetbuilder et hb (alias de la première) sont accessibles en globale dans les scripts
Le builder organise les dépendances de manière "flat" et gère la transitivité des dépendances.
Il impose la déclaration de dépendance en version fixe (sans ^, ~ ou *) afin de pérenniser les versions.
Il impose également une structure du fichier `package.json légèrement différente de celle par défaut :
dependencies doivent impérativement être définies dans la clé appDependenciesdevDependencies doivent impérativement être définies dans la clé buildAndTestDependenciesAfin que les dépendances applicatives et les dépendances de construction/test ne rentrent pas en conflit, les dépendances sont installées dans deux répertoires différents à l'intérieur du répertoire node_modules :
Pour que le serveur nodejs sache lire les dépendances dans ce nouveau répertoire node_modules/app un fichier "bootstrap" nommé index.ts permet de démarrer le serveur.
Lorsque le builder détecte par transitivité une dépendance dont la version n'est pas fixe (ex: ^3.0.0), il récupère la dernière version correspondante sur le repository courant et la fixe dans un objet ____HORNET-BUILDER____DO_NOT_MODIFY_THIS_OBJECT____ qui est sauvegardé à la fin du fichier package.json.
Cet objet ne doit surtout pas être modifié manuellement !!
Exemple d'un fichier package.json complet avec version fixée par le builder :
{
"name": "applitutoriel",
"version": "5.0.X",
"main": "index.js",
"description": "Application tutoriel utilisant le Framework hornet 5.0.X",
"tsDefinitionDependencies": {
...
},
"appDependencies": {
...
},
"buildAndTestDependencies": {
...
},
"author": "MAEDI",
"____HORNET-BUILDER____DO_NOT_MODIFY_THIS_OBJECT____": {
"current": "b9265f7937e0a4a52491f52fe18fe26a537052e8",
"history": {
"b9265f7937e0a4a52491f52fe18fe26a537052e8": {
"date": "2015-11-09T10:02:18.543Z",
"deps": {"amdefine":"1.0.0","base62":"1.1.0","charenc":"0.0.1","commoner":"0.10.3","crypt":"0.0.1","install":"0.1.8","jstransform":"11.0.3","object-assign":"2.1.1","passport-strategy":"1.0.0"}
}
}
}
}
Exemple:
cd D:\dev\workspace\applitutoriel\applitutoriel-js
hornetbuilder (ou hb) suivi de la tâche à exécuter. Exemple:$ hb test
Une aide est fournie en tapant la commande
$ hb --help
Les options suivantes sont alors proposées:
| Option | Rôle |
|---|---|
| -V, --version | Affiche la version du builder |
| -d, --debug | Active les messages de logs du builder en mode debug |
| --show-webpack-files | Active le listing des fichiers embarqués par webpack lors de la construction du bundle de fichiers clients. Note: Les fichiers sont triés par taille croissante |
| -i, --ide | Indique que c'est l'IDE qui gère la compilation des fichiers .ts, .d.ts et .map. Dans ce mode la compilation des fichiers TypeScripts est désactivée ainsi que les watchers associés. De même, la tâche clean ne supprime plus ces fichiers. Cette option doit être utilisée dès lors qu'une IDE est lancé sur les projets |
| -r, --registry | Permet d'utiliser un repository spécifique. Par défaut le repository défini dans le fichier .npmrc est utilisé |
| --publish-registry | Permet de spécifier un repository npm spécifique pour la publication autre que celui par défaut. Par défaut le repository défini dans le fichier .npmrc est utilisé |
| -f, --force | Permet de forcer la mise à jour des dépendances |
| --skipTests | Permet de ne pas exécuter les tests si ceux-ci doivent être exécutés (ex: tâche package) |
| --skipMinified | Permet de ne pas minifier les chuncks |
| -p, --debugPort | Indique le port utilisé par node pour permettre la connexion d'un debugger externe" |
| --lintRules | Indique un fichier de rules tslint.json autre que celui utilisé par le builder |
| --lintReport | Indique le format de sortie pour tslint : prose (défaut), json, verbose, full, msbuild |
package.jsoncf : Principe de gestion des dépendances
Le package.json diffère de la norme npm concernant l'ajout de dépendances ceci afin de gérer les dépendances fixes avec le builder.
dependencies => appDependenciesdevDependencies => buildAndTestDependencies{
"appDependencies": {
"hornet-js-components": "5.0.X"
...
},
"buildAndTestDependencies": {
"chai": "1.10.0"
...
},
...
}
Afin de bénéficier de la compilation Typescript pour les modules d'un projet, il est possible de spécifier les fichiers de définition typescript spécifique au projet dans la section tsDefinitionDependencies. Celles-ci sont automatiquement ajouté au répertoire definition-ts à la racine du projet.
Le projet peut également avoir ses propres fichiers de définition en plus de ceux proposés par le framework.
"tsDefinitionDependencies": {
"hornet-js-ts-typings": "5.0.X",
"hornet-js-utils-dts": "5.0.X",
"hornet-js-core-dts": "5.0.X",
"hornet-js-components-dts": "5.0.X",
"hornet-js-cas-dts": "5.0.X"
}
package.json{
"name": "applitutoriel",
"version": "5.0.X",
"main": "index.js",
"description": "Application tutoriel utilisant le Framework hornet 5.0.X",
"bugs": {
"url": "https://github.com/diplomatiegouvfr/applitutoriel-js/issues"
},
"repository": {
"type": "git",
"url": "git+https://github.com/diplomatiegouvfr/applitutoriel-js.git"
},
"tsDefinitionDependencies": {
"hornet-js-ts-typings": "5.0.X",
"hornet-js-utils-dts": "5.0.X",
"hornet-js-core-dts": "5.0.X",
"hornet-js-components-dts": "5.0.X",
"hornet-js-cas-dts": "5.0.X"
},
"appDependencies": {
"hornet-js-components": "5.0.X",
"hornet-js-core": "5.0.X",
"hornet-js-utils": "5.0.X",
"hornet-js-cas": "5.0.X",
"connect-flash": "0.1.1",
"node-jsx": "0.13.3",
"passport": "0.2.1",
"passport-local": "1.0.0",
"sha1": "1.1.1"
},
"buildAndTestDependencies": {
"chai": "1.10.0",
"chai-jquery": "2.0.0",
"cheerio": "0.18.0",
"sinon": "1.13.0",
"sinon-chai": "2.7.0"
},
"author": "MAEDI",
"____HORNET-BUILDER____DO_NOT_MODIFY_THIS_OBJECT____": {
"current": "92f3196ce9c86b9708e3273152885f52e18443a3",
"history": {
"92f3196ce9c86b9708e3273152885f52e18443a3": {
"date": "2016-02-09T13:23:55.506Z",
"deps": {"amdefine":"1.0.0","base62":"1.1.0","charenc":"0.0.1","commoner":"0.10.4","crypt":"0.0.1","jstransform":"11.0.3"}
}
}
}
}
tsconfig.jsonLes projets doivent impérativement avoir un fichier tsconfig.json à la racine.
Celui-ci regroupe les informations de compilation typescript nécessaire au projet.
ex :
{
"compilerOptions": {
"target": "ES5",
"module": "commonjs",
"moduleResolution": "classic",
"experimentalDecorators": true,
"jsx": "react",
"sourceMap": true,
"noResolve": true
},
"exclude": [
"node_modules"
]
}
builder.jsLes projets doivent comporter à la racine un fichier builder.js afin de déterminer le type de l'application : application, module, ... ainsi que les différentes tâches à éxécuter nécessaire à la construction.
Ce fichier doit comporter au minimum le code suivant:
module.exports = {
type: "application",
gulpTasks: function (gulp, project, conf, helper) {
},
externalModules: {
enabled: false,
directories: [
]
}
};
type indique au builder le type de projet actuel. Pour une application le type doit toujours être applicationgulpTasks permet :
gulpgulp.beforeTask(taskName, func) et gulp.afterTask(taskName, func)gulp.addTaskDependency(taskName, dependencyTaskName)externalModules permet de déclarer des dépendances à partir de répertoires externesExemple:
...
gulpTasks: function (gulp, project, conf, helper) {
gulp.task("maNouvelleTache", function(done) {
helper.info("Execution de 'maNouvelleTache'");
done();
});
},
...
$ hb maNouvelleTache
hornetbuilder fourni les tâches suivantes afin de gérer les dépendances d'un projet :
| Tâche | Rôle | Dépendances |
|---|---|---|
| dependencies:clean | supprime les dépendances applicatives (répertoire node_modules/app) | |
| dependencies:clean-build | supprime les dépendances de construction/test (répertoire node_modules/buildntest) | |
| dependencies:clean-all | supprime toutes les dépendances | |
| dependencies:check-app | vérifie la conformité des versions des dépendances applicatives déclarées | |
| dependencies:check-ts-definition | vérifie la conformité des versions des fichiers de définition Typescript | |
| dependencies:change-app | vérifie si les dépendances applicatives ont été modifiées | dependencies:check-app |
| dependencies:fix-app | Calcule l'arbre de dépendances applicatives et fixe les versions des dépendances transitives déclarées avec un ^, ~ ou * | dependencies:change-app |
| dependencies:install-ts-definition | Installe les fichiers de définition | dependencies:check-ts-definition |
| dependencies:install-app | Installe les dépendances applicatives | dependencies:fix-app |
| dependencies:install | Installe les dépendances applicatives et les fichiers de définitions | dependencies:install-ts-definition et dependencies:install-app |
| install | Alias de "dependencies:install" | dependencies:install |
hornetbuilder fourni les tâches suivantes afin de compiler les sources d'un projet :
| Tâche | Rôle | Dépendances |
|---|---|---|
| compile:ts | Transpile les sources TS en Javascript. S'exécute uniquement si l'option "-i" (--ide) n'est pas utilisée | clean |
| compile | Transpile les sources TS en Javascript. | dependencies:install compile:ts |
hornetbuilder fourni les tâches suivantes afin d'exécuter les tests d'un projet :
| Tâche | Rôle | Dépendances |
|---|---|---|
| prepare:testSources | Copie les sources originales et compilées dans le répertoire de travail des tests : istanbul | compile |
| test:instrument | Défini les instruments de couverture de code sur les sources | prepare:testSources |
| test | Exécute les tests unitaires et la mesure de couverture de code | dependencies:install test:instrument |
hornetbuilder fourni les tâches suivantes afin de nettoyer un projet :
| Tâche | Rôle | Dépendances |
|---|---|---|
| clean:test | Supprime le dossier istanbul ainsi que les fichiers générés (.js, .map et .d.ts dans le dossier de tests) | |
| clean | Supprime les fichiers générés (.js, .map et .d.ts dans le dossier de sources) | clean:test |
hornetbuilder fourni les tâches suivantes afin de construire les livrables d'un projet :
| Tâche | Rôle | Dépendances |
|---|---|---|
| prepare-package | Lance WebPack pour la construction du js client (mode debug) | |
| prepare-package:minified | Lance WebPack avec la minification pour la construction du js client | |
| prepare-package:spa | Prépare les fichiers à packager pour un projet en FullSpa | |
| package-zip-static | Construit le livrable statique | prepare-package:minified |
| package-zip-dynamic | Construit le livrable dynamique | prepare-package:minified |
| package | Lance les tests puis construit tous les livrables | test package-zip-static package-zip-dynamic |
hornetbuilder fourni les tâches suivantes afin d'outiller le démarrage d'une application en développement
| Tâche | Rôle | Dépendances |
|---|---|---|
| watch:ts | Ecoute les modifications sur les fichiers TS et les recompile à la volée. S'exécute uniquement si l'option "-i" (--ide) n'est pas utilisée | |
| watch:serveur | Ecoute les modifications sur les fichiers et redémarre le serveur node pour les prendre en compte. Démarre nodejs en mode development | watch:ts |
| watch:serveur-prod | Equivalent à watch:serveur mais avec nodejs en mode production | watch:ts |
| watch:client | Ecoute les modifications sur les fichiers et relance WebPack à la volée. Lance WebPack en mode development. | watch:ts |
| watch:client-prod | Equivalent à watch:client mais avec WebPack en mode production | watch:ts |
| watch | Compile et écoute les modifications pour redémarrer nodejs et relancer WebPack si besoin. mode : development | compile watch:client watch:serveur |
| watch-prod | Compile et écoute les modifications pour redémarrer nodejs et relancer WebPack si besoin. mode : production | compile watch:client-prod watch:serveur-prod |
| w | Alias de "watch" | watch |
| wp | Alias de "watch-prod" | watch-prod |
hornetbuilder fourni les tâches suivantes afin de construire des rapports de qualimétrie :
| Tâche | Rôle | Dépendances |
|---|---|---|
| lint | Lance le tslint sur les sources ts (qualité de code) |
$ hb lint
$ hb lint --lintReport json
Lors de la première utilisation du builder et peu importe la commande, le builder va installer les dépendances de construction/test afin que celles-ci soient disponibles dans le fichier builder.js. Cela permet d'ajouter à un projet des tâches de construction dépendantes de modules non fournis par le framework. Il sera ainsi possible d'écrire dans le fichier builder.js :
var maDependanceSpecifique = require("maDependanceSpecifique");
Dès la première utilisation du builder sur un projet, il est possible d'utiliser la commande :
$ hb watch
Dans un ide qui compile automatique les fichiers typescript, il est recommandé d'utiliser l'option -i
$ hb watch -i
ou bien :
$ hb w -i
Les dépendances entre les tâches du builder font que l'arbre des dépendances applicatives va être calculé, que les versions non fixées vont l'être, que l'ensemble des dépendances vont s'installer, que les sources vont se compiler, que le serveur nodejs va démarrer et que les modifications des fichiers seront écoutées.
Il est néanmoins possible de lancer indépendemment les différentes tâches :
$ hb dependencies:install
$ hb compile
$ hb watch
$ hb test
Exécute les tests et fourni sur la console :
$ hb package
Construit les différents livrables et les place dans le répertoire target à la racine du projet.
$ hb publish --publish-registry <URL>
Publie le module sur un repository spécifique.
hornet-js-builder est sous licence cecill 2.1.
Site web :
FAQs
Builder/loader des Applications Hornet, Wrapper NPM permettant de fixer les versions des dépendances
The npm package hornet-js-builder receives a total of 4 weekly downloads. As such, hornet-js-builder popularity was classified as not popular.
We found that hornet-js-builder demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."