scripts

Description

La propriété "scripts" de de votre fichier package.json supporte un certain nombre de scripts intégrés et leurs événements de cycle de vie prédéfinis ainsi que des scripts arbitraires. Ceux-ci peuvent tous être exécutés en exécutant npm run-script <stage> ou npm run <stage> pour faire court. Les pré et post-commandes avec des noms correspondants seront également exécutées pour ceux-ci (par exemple premyscript, myscript, postmyscript). Les scripts des dépendances peuvent être exécutés avec npm explore <pkg> -- npm run <stage>.

Pre & Post Scripts

Pour créer des scripts « pre » ou « post » pour tout script défini dans la section "scripts" du package.json, il suffit de créer un autre script avec un nom correspondant et d’ajouter « pre » ou « post » au début de ceux-ci.

 { 
 "scripts" : { 
 "precompress" : "{{ exécute AVANT le script `compress` }}", 
 "compress" : "{{exécute la commande pour compresser les fichiers }}", 
 "postcompress" : "{{ exécute après le script `compress` }}" 
 } 
 } 

Scripts du cycle de vie

Il y a des scripts spéciaux du cycle de vie qui se produisent seulement dans certaines situations. Ces scripts se produisent en plus du script « pre » et « post ».

• prepare, prepublish, prepublishOnly, prepack, postpack

prepare (depuis [email protected])

• Exécution avant l’empaquetage du paquet
• Exécution avant la publication du paquet
• Exécution sur le local npm install sans aucun argument
• Exécution après prepublish, mais avant prepublishOnly
• NOTE : Si un paquet en cours d’installation par git contient un script prepare, ses dependencies et devDependencies seront installés, et le script prepare sera exécuté, avant que le paquet soit empaqueté et installé.

prepublish (DEPRECATED)

• Même chose que prepare

prepublishOnly

• Exécution AVANT que le paquet soit préparé et empaqueté, UNIQUEMENT sur npm publish.

prepack

• Exécution AVANT l’empaquetage d’une archive (sur « npm pack« , « npm publish« , et lors de l’installation d’une dépendance git).
• NOTE : « npm run pack » n’est PAS identique à « npm pack« . « npm run pack » est un nom de script arbitraire défini par l’utilisateur, alors que, « npm pack » est une commande définie par la CLI.

postpack

• Exécution APRÈS la génération du tarball et son déplacement vers sa destination finale.

Préparation et prépublication

Note de dépréciation : prepublish

Depuis [email protected], le CLI de npm a exécuté le script prepublish à la fois pour npm publish et npm install, car c’est un moyen pratique de préparer un paquet pour l’utiliser (certains cas d’utilisation courants sont décrits dans la section ci-dessous). Il s’est également avéré être, en pratique, très confus. À partir de [email protected], un nouvel événement a été introduit, prepare, qui préserve ce comportement existant. Un nouvel événement, prepublishOnly, a été ajouté en tant que stratégie de transition pour permettre aux utilisateurs d’éviter le comportement confus des versions npm existantes et de n’exécuter que sur npm publish (par exemple, exécuter les tests une dernière fois pour s’assurer qu’ils sont en bon état).

Voir https://github.com/npm/npm/issues/10074 pour une justification beaucoup plus longue, avec des lectures supplémentaires, pour ce changement.

Cas d’utilisation

Si vous devez effectuer des opérations sur votre paquet avant qu’il ne soit utilisé, d’une manière qui ne dépend pas du système d’exploitation ou de l’architecture du système cible, utilisez un script prepublish. Cela comprend des tâches telles que :

• Compilation du code source CoffeeScript en JavaScript.
• Création de versions minifiées du code source JavaScript.
• Récupération de ressources distantes que votre paquet utilisera.

L’avantage de faire ces choses au moment prepublish est qu’elles peuvent être faites une fois, en un seul endroit, ce qui réduit la complexité et la variabilité. En outre, cela signifie que :

• Vous pouvez dépendre de coffee-script en tant que devDependency, et doncvos utilisateurs n’ont pas besoin de l’avoir installé.
• Vous n’avez pas besoin d’inclure des minifieurs dans votre paquet, réduisant la taille pour vos utilisateurs.
• Vous n’avez pas besoin de compter sur le fait que vos utilisateurs ont curl ou wget ou d’autres outils système sur les machines cibles.

Ordre de fonctionnement du cycle de vie

npm publish

• prepublishOnly
• prepare

.

• prepublish
• publish
• postpublish

npm pack

• prepack
• postpack

npm install

• preinstall
• install
• postinstall

Déclenche également

• . prepublish (quand sur local)
• prepare (quand sur local)

npm start

npm run start a un raccourci npm start.

• prestart
• start
• poststart

Valeurs par défaut

npm définira par défaut certaines valeurs de script en fonction du contenu du paquet.

• "start": "node server.js":

  S’il y a un fichier server.js à la racine de votre paquet, alors npm mettra par défaut la commande start à node server.js.

• "install": "node-gyp rebuild":

  S’il y a un fichier binding.gyp à la racine de votre paquet et que vous n’avez pas défini vos propres scripts install ou preinstall, npm proposera par défaut la commande install pour compiler en utilisant node-gyp.

User

Si npm a été invoqué avec les privilèges de root, alors il changera l’uid en compte utilisateur ou uid spécifié par la configuration user, qui est par défaut nobody. Définissez le drapeau unsafe-perm pour exécuter les scripts avec des privilègesroot.

Environnement

Les scripts de paquetage s’exécutent dans un environnement où de nombreux éléments d’information sont mis à disposition concernant la configuration de npm et l’état actuel du processus.

path

Si vous dépendez de modules qui définissent des scripts exécutables, comme les testsuites, alors ces exécutables seront ajoutés au PATH forexécution des scripts. Donc, si votre package.json a ceci:

 { 
 "name" : "foo", 
 "dependencies" : { 
 "bar" : "0.1.x" 
 }, 
 "scripts" : { 
 "start" : "bar ./test" 
 } 
 } 

alors vous pourriez exécuter npm start pour exécuter le script bar, qui est exporté dans le répertoire node_modules/.bin sur npm install.

package.json vars

Les champs package.json sont plaqués sur le préfixe npm_package_. Ainsi, par exemple, si vous aviez {"name":"foo", "version":"1.2.5"} dans votre fichierpackage.json, alors vos scripts de paquet auraient la variable d’environnementnpm_package_name définie sur « foo », et lanpm_package_version définie sur « 1.2.5 ». Vous pouvez accéder à ces variables dans votre code avec process.env.npm_package_name etprocess.env.npm_package_version, et ainsi de suite pour les autres champs.

configuration

Les paramètres de configuration sont mis dans l’environnement avec le préfixenpm_config_. Par exemple, vous pouvez voir la rootconfig effective en vérifiant la variable d’environnement npm_config_root.

Spécial : objet « config » de package.json

Les clés « config » de package.json sont écrasées dans l’environnement s’il existe un paramètre de configuration de <name>:<key>. Par exemple, si le package.json a ceci:

 { 
 "name" : "foo", 
 "config" : { 
 "port" : "8080" 
 }, 
 "scripts" : { 
 "start" : "node server.js" 
 }. 
 } 

et le server.js est celui-ci:

 http.createServer(...).listen(process.env.npm_package_config_port) 

alors l’utilisateur pourrait changer le comportement en faisant:

 npm config set foo:port 80 

événement du cycle de vie actuel

Enfin, la variable d’environnement npm_lifecycle_event est définie à n’importe quelle étape du cycle en cours d’exécution. Ainsi, vous pourriez avoir un seul script utilisé pour différentes parties du processus qui change en fonction de ce qui se passe actuellement.

Les objets sont aplatis suivant ce format, donc si vous aviez{"scripts":{"install":"foo.js"}} dans votre package.json, alors vous verriez ceci dans le script:

 process.env.npm_package_scripts_install === "foo.js" 

Exemples

Par exemple, si votre package.json contient ceci:

 { 
 "scripts" : { 
 "install" : "scripts/install.js", 
 "postinstall" : "scripts/install.js", 
 "uninstall" : "scripts/uninstall.js" 
 } 
 } 

alors scripts/install.js sera appelé pour les étapes d’installation et de post-installation du cycle de vie, et scripts/uninstall.jssera appelé lorsque le paquet sera désinstallé. Puisquescripts/install.js s’exécute pour deux phases différentes, il serait sage dans ce cas de regarder la variable d’environnement npm_lifecycle_event.

Si vous voulez exécuter une commande make, vous pouvez le faire. Cela fonctionne parfaitement :

 { 
 "scripts" : { 
 "preinstall" : "./configure", 
 "install" : "make && make install", 
 "test" : "make test" 
 }. 
 } 

Sortie

Les scripts sont exécutés en passant la ligne comme argument de script à sh.

Si le script sort avec un code autre que 0, alors cela fera avorter leprocess.

Notez que ces fichiers de script n’ont pas besoin d’être des programmes nodejs ou mêmejavascript. Ils doivent juste être une sorte de fichier exécutable.

Scripts hook

Si vous voulez exécuter un script spécifique à un événement spécifique du cycle de vie pour TOUS les paquets, alors vous pouvez utiliser un script hook.

Placez un fichier exécutable à node_modules/.hooks/{eventname}, et il sera exécuté pour tous les paquets quand ils passent par ce point dans le cycle de vie des paquets pour tous les paquets installés dans cette racine.

Les scripts hook sont exécutés exactement de la même manière que les scripts package.json.C’est-à-dire qu’ils sont dans un processus enfant séparé, avec l’env décrit ci-dessus.

Bonnes pratiques

• Ne sortez pas avec un code d’erreur non nul à moins que vous ne le pensiez vraiment.Sauf pour les scripts de désinstallation, cela provoquera l’échec de l’action npm, et potentiellement son retour en arrière. Si l’échec est mineur ou seulement empêchera certaines fonctionnalités optionnelles, alors il est préférable de juste imprimer un avertissement et de sortir avec succès.
• Essayez de ne pas utiliser de scripts pour faire ce que npm peut faire pour vous. Lisez à traverspackage.json pour voir toutes les choses que vous pouvez spécifier et activer en décrivant simplement votre paquet de manière appropriée. En général, cela conduira à un état plus robuste et cohérent.
• Inspectez l’env pour déterminer où placer les choses. Par exemple, si la variable d’environnement npm_config_binroot est définie sur /home/user/bin, alors n’essayez pas d’installer des exécutables dans /usr/local/bin. L’utilisateur l’a probablement configuré de cette façon pour une raison.
• Ne préfixez pas vos commandes de script avec « sudo ». Si les autorisations root sont requises pour une raison quelconque, alors cela échouera avec cette erreur, et l’utilisateur sudo la commande npm en question.
• N’utilisez pas install. Utilisez un fichier .gyp pour la compilation, et prepublishpour tout le reste. Vous ne devriez presque jamais avoir à définir explicitement un script apreinstall ou install. Si vous faites cela, veuillez considérer s’il y a une autre option. La seule utilisation valide de install ou preinstallscripts est pour la compilation qui doit être faite sur l’architecture cible.

See Also

• npm run-script
• package.json
• npm developers
• npm install

.