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é buildDependenciesdevDependencies doivent impérativement être définies dans la clé testDependenciesAfin 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.1.X",
"main": "index.js",
"description": "Application tutoriel utilisant le Framework hornet 5.1.X",
"tsDefinitionDependencies": {
...
},
"appDependencies": {
...
},
"buildDependencies": {
...
},
"testDependencies": {
...
},
"author": "MEAE - Ministère de l'Europe et des Affaires étrangères",
"____HORNET-BUILDER____DO_NOT_MODIFY_THIS_OBJECT____": {
"current": "b9265f7937e0a4a52491f52fe18fe26a537052e8",
"history": {
"b9265f7937e0a4a52491f52fe18fe26a537052e8": {
"version": "5.1.X",
"date": "2017-03-09T10:02:18.543Z",
"deps": {"amdefine":"X.X.X",...}
}
}
}
}
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 |
| -D, --docker [options]' | Exécute les commandes du Builder dans le container Docker nodeJS |
| --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 |
| --webpackVisualizer | Visualisation de la répartition des sources projets et node modules dans un chart, /static/dev/webpack-visualizer.html |
| -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'un 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 |
| --ignoreApp | ne prend pas la version de dépendance applicative, mais la plus récente |
| --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 |
| --file | Indique le chemin d'un fichier |
| --dev | active le mode developpement |
| --offline | active le mode offline pour la récupération des dépendances, ex : coupure réseau. Prerequis avoir les node_modules, ajouter fetch-retries=0 dans .npmrc |
| --versionFix | Indique la version ou suffixe si commence par '-', '.' ou si null calcule un suffixe avec timestamp. |
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 => testDependenciesbuildDependencies{
"appDependencies": {
"hornet-js-components": "5.1.X"
...
},
"testDependencies": {
"hornet-js-test": "5.1.X"
...
},
"buildDependencies": {
"md-loader": "X"
...
}, ...
}
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.1.X",
"hornet-js-utils-dts": "5.1.X",
"hornet-js-core-dts": "5.1.X"
...
}
package.json{
"name": "applitutoriel",
"version": "5.1.X",
"main": "index.js",
"description": "Application tutoriel utilisant le Framework hornet 5.1.X",
"bugs": {
"url": "https://github.com/diplomatiegouvfr/applitutoriel-js/issues"
},
"repository": {
"type": "git",
"url": "git+https://github.com/diplomatiegouvfr/applitutoriel-js.git"
},
"tsDefinitionDependencies": {
"applitutoriel-js-common-dts": "5.1.X",
"hornet-js-ts-typings": "5.1.X",
"hornet-js-utils-dts": "5.1.X",
"hornet-js-core-dts": "5.1.X",
"hornet-js-components-dts": "5.1.X",
"hornet-js-react-components-dts": "5.1.",
"hornet-js-react-component-chart-dts": "5.1.X",
"hornet-js-passport-dts": "5.1.X",
"hornet-js-test-dts": "5.1.X"
},
"appDependencies": {
"hornet-js-bean": "5.1.X",
"hornet-js-components": "5.1.X",
"hornet-js-react-components": "5.1.X",
"hornet-js-react-component-chart": "5.1.X",
"hornet-js-core": "5.1.X",
"hornet-js-utils": "5.1.X",
"hornet-js-passport": "5.1.X",
"hornet-themes-intranet": "5.1.X",
"jsonwebtoken": "7.3.0",
"connect-flash": "0.1.1",
"passport": "0.2.1",
"passport-local": "1.0.0",
"sha1": "1.1.1"
},
"buildDependencies": {},
"testDependencies": {
"hornet-js-test": "5.1.X"
},
"author": "MEAE - Ministère de l'Europe et des Affaires étrangères",
"____HORNET-BUILDER____DO_NOT_MODIFY_THIS_OBJECT____": {
"current": "92f3196ce9c86b9708e3273152885f52e18443a3",
"history": {
"92f3196ce9c86b9708e3273152885f52e18443a3": {
"version": "5.1.X",
"date": "2017-03-09T13:23:55.506Z",
"deps": {"amdefine":"X.X.X", ...}
}
}
}
}
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",
"static"
]
}
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: [
]
},
config : {
routesDirs: [
"." + path.sep + "routes",
"." + path.sep + "routes-bis"
],
clientExclude: {
dirs: [
path.join("src","services","back"),
"config",
"src/middleware"],
filters: [
path.join("src","services","data")+"/.*-data\.*"
],
modules: [
"config",
"continuation-local-storage",
"pdfmake"
]
},
clientNoParse : []
typescript : {
bin: "~/Dev/node-v6.9.0-linux-x64/lib/node_modules/typescript" // permet de spécifier une version de typescript autre que builder
},
webpack: {
// permet de surcharger la configration webpack pour des besoins spécifiques
},
karma: {
// permet de surcharger la configuration karmaJs pour des besoins spécifiques
},
template: {
// permet de surcharger la configuration de la tâche de templating html
}
}
};
La clé type indique au builder le type de projet actuel. Pour une application le type doit toujours être application (types possibles : "parent", "application", "application-server", "module", "theme", "custom").
La fonction gulpTasks permet :
gulpgulp.beforeTask(taskName, func) et gulp.afterTask(taskName, func)gulp.addTaskDependency(taskName, dependencyTaskName)L'objet externalModules permet de déclarer des dépendances à partir de répertoires externes
L'objet config permet de surcharger la configuration du builder dans chaque application
routesDirs permet de spécifier les répertoires des routes pour le code splitting automatiqueclientExclude est un raccourci pour modifier la conf webpack et rajouter des externalsclientNoParse est un raccourci pour modifier la conf webpack et rajouter des module.noParsetypescript.bin permet de préciser une autre version de typescript pour la transpilation que celle utiliser ambarquée par le builderwebpack permet de configurer WebPack pour des projet ayant besoin de loader particulier...karma permet de configurer karma (autre navigateur...)spaResources liste de filtres permettant d'ajouter des ressources pour la génération de chunck SPAdllEntry permet de préciser des dll webpack (gain de temps de construction des chunck)template permet de configurer la tâche de templating html
dir répertoire des templates (par défault 'template')context objet disponible pour le templating, par défaut :
ou tableau de :dir répertoire des templates (par défault 'template')context objet disponible pour le templating, par défaut :context contiendra par défaut :
{
project:
{
name: project.name,
version: project.version,
static: "static-" + project.version + "/"
}
}
Exemple:
...
gulpTasks: function (gulp, project, conf, helper) {
gulp.task("maNouvelleTache", function(done) {
helper.info("Execution de 'maNouvelleTache'");
done();
});
},
...
$ hb maNouvelleTache
La configuration par défaut du builder est la suivante:
var defaultConf = {
src: "src", // répertoire des sources
test: "test", // répertoire des tests
static: "static", // répertoire des statics pour la génération des chuncks
js: "js",
config: "./config", // répertoire du fichier de configuration de l'application
generatedTypings: {
dir: ".",
file: "definition.d.ts"
},
clientJs: "client.js",// point d'entrée pour Webpack
routesDirs: ["." + path.sep + "routes"],// répertoire des routes (fichiers avec suffixe '-routes.js')
componentsDirs: [path.join("..", "src")],// répertoire des pages React (fichiers avec suffixe '-page.jsx')
testWorkDir: "istanbul",// répertoire de travail pour les tests (transpilation, rapports...)
mocha: { // configuration pour mocha (rapport de test (passants / non passants)
reporter: process.env.NODE_ENV === "integration" ? "xunit" : "spec",
reporterOptions: {
output: "test-results.xml"
}
//,"grep": "Router constructor"
},
istanbul: { // configuration pour istanbul (rapport de taux de couverture des tests
dir: path.join(testWorkDir, "coverage"),
reporters: ["lcov", "text", "text-summary", "cobertura"],
reportOpts: {dir: path.join(testWorkDir, "reports")}
},
istanbulOpt: {
includeUntested: true
},
webPackConfiguration: { // configuration pour webpack
module: []
},
webPackMinChunks: 3,
webPackLogAddedFiles: true,
template: {
context: {}
}
};
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:clean-fix | supprime toutes les dépendances fixées, à utiliser avec l'option -f | |
| 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 *. Si plusieurs versions la plus récente est prise sauf si elle est fixée dans les depenances applicatives. | 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-app-themes | Installe les dépendances applicatives de type theme dans les staic de l'application | dependencies:fix-app |
| dependencies:install-test | Installe les dépendances de test | |
| 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 |
| versions:set | permet de changer la version du projet |
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. Cette tâche exécutera un dependencies:install en plus de la tâche clean de la commande compile:ts | 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 |
| test:karma | Exécute les tests basées sur KarmaJs | dependencies:install compile |
hornetbuilder fournit 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 |
| clean-all | Supprime tous les fichiers et dépendances | clean, dependencies:clean-all |
hornetbuilder fourni les tâches suivantes afin de construire les livrables d'un projet :
| Tâche | Rôle | Dépendances |
|---|---|---|
| prepare-package-dll | Lance WebPack pour la construction des dll's js client | |
| prepare-package | Lance WebPack pour la construction du js client (mode debug) et copie les livrables dans le répertoire target | prepare-package:minified, prepare-all-package |
| 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 | |
| prepare-all-package | copie les livrables dans le répertoire target | |
| prepare-zip-static | Construit le livrable statique | prepare-package:minified, zip-static |
| prepare-zip-dynamic | Construit le livrable dynamique | prepare-package:minified, zip-dynamic |
| zip-static | Construit le livrable statique (zip) | |
| zip-dynamic | Construit le livrable dynamique (zip) | |
| package | Lance les tests puis construit tous les livrables | compile test template-html package-zip-static package-zip-dynamic |
| template-html | Lance le templating html |
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 automatiquement 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 fournit sur la console :
Les fichiers exécutés doivent se trouver dans le répertoire ./test et se nommer *-spec.js sachant que la phase de compile passe avant.
$ hb test:karma
$ hb test:karma --file ./test/page/test.karma.js
Le test à exécuter est donné par le paramètre -file ou si aucun n'est précisé, il prend la configuration karma et par défaut c'est tests.webpack.js. Ce dernier référence tous les tests à exécuter grace à require, exemple qui tire tous les fichiers *.karma.js dans le répertoire test:
var context = require.context('./test', true, /\.karma\.js$/);
context.keys().forEach(context);
Les rapports sont générés dans le répertoire ./test_report
Le navigateur utilisé par défaut est Firefox. Pour en ajouter ou en utiliser un autre, il faut surcharger la configuration dans le fichier builder.js, exemple :
config : {
....
..
karma: {
browsers: ["Chrome", "Firefox"],
}
}
Par défaut, lorsque les tests sont ouverts dans un navigateur, aucune feuille de style hornet n'est chargée. Il est possible de surcharger les templates karma:
config : {
....
..
karma: {
template: {
debug: "./test/template/debug.html",
context: "./test/template/context.html",
clientContext: "./test/template/client_with_context.html"
}
}
}
les templates fournis nécessitent de démarrer un serveur de thèmes.
$ hb template-html
Lance le templating basé sur EJS et écrit les fichiers dans 'static/html' du projet.
Si l'objet de configuration tempate est un tableau, il lancera autant de templating que d'élément dans le tableau, exemple :
template: [
{
context: [{error: "404", suffixe: "_404", message: "Oops! Nous ne trouvons pas ce que vous cherchez!"}, {error: "500", suffixe: "_500", message: "Oops! Une erreur est survenue!"}],
dir: "./template/error",
dest: "/error"
}, {
context: {message: "test template"}
}
]
Dans cet exemple, le templating suivant est lancé :
$ 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.
$ hb versions:set --versionFix=1.2.3
Modifie la version du projet ou des projets si on est sur un type parent en '1.2.3'.
$ hb versions:set --versionFix=
Modifie la version du projet en suffixant par un timestamp 'YYYYMMDDHHmmss'.
$ hb versions:set --versionFix=\'-123\'
Modifie la version du projet en suffixant par '-123', il faut echapper les caractères `.
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 2 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."