scripts

Descripción

La propiedad "scripts" de su archivo package.json admite una serie de scripts incorporados y sus eventos de ciclo de vida preestablecidos, así como scripts arbitrarios. Todos ellos pueden ser ejecutados mediante la ejecución de npm run-script <stage> o npm run <stage> para abreviar. También se ejecutarán comandos previos y posteriores con nombres coincidentes (por ejemplo, premyscript, myscript, postmyscript). Los scripts de las dependencias pueden ejecutarse con npm explore <pkg> -- npm run <stage>.

Pre & Post Scripts

Para crear scripts «pre» o «post» para cualquier script definido en la sección "scripts" del package.json, simplemente cree otro script con un nombre coincidente y añada «pre» o «post» al comienzo de los mismos.

 { 
 "scripts": { 
 "precompress": "{{ ejecuta ANTES del script `compress` }}", 
 "compress": "{{ ejecuta el comando para comprimir los archivos }}", 
 "postcompress": "{{ ejecuta después del script `compress` }}" 
 } 
 } 

Scripts del ciclo de vida

Hay algunos scripts especiales del ciclo de vida que ocurren sólo en ciertas situaciones. Estos scripts ocurren en adición al script «pre» y «post».

• prepare, prepublish, prepublishOnly, prepack, postpack

prepare (desde [email protected])

• Se ejecuta ANTES de empaquetar el paquete
• Se ejecuta ANTES de publicar el paquete
• Se ejecuta en local npm install sin argumentos
• Se ejecuta DESPUÉS de prepublish, pero ANTES de prepublishOnly
• NOTA: Si un paquete que se está instalando a través de git contiene un script prepare, se instalarán sus dependencies y devDependencies, y se ejecutará el script de preparación, antes de empaquetar e instalar el paquete.

prepublish (DEPRECATED)

• Igual que prepare

prepublishOnly

• Se ejecuta ANTES de preparar y empaquetar el paquete, SOLO en npm publish.

prepack

• Se ejecuta ANTES de empaquetar un tarball (en «npm pack«, «npm publish«, y cuando se instala una dependencia de git).
• NOTA: «npm run pack» NO es lo mismo que «npm pack«. «npm run pack» es un nombre de script arbitrario definido por el usuario, mientras que «npm pack» es un comando definido por la CLI.

postpack

• Se ejecuta DESPUÉS de que el tarball haya sido generado y trasladado a su destino final.

Preparar y prepublicar

Nota de declinación: prepublish

Desde [email protected], la CLI de npm ha ejecutado el script prepublish tanto para npm publish como para npm install, porque es una forma conveniente de preparar un paquete para su uso (algunos casos de uso común se describen en la sección siguiente). También ha resultado ser, en la práctica, muy confuso. A partir de [email protected], se ha introducido un nuevo evento, prepare, que preserva este comportamiento existente. Se ha añadido un nuevo evento, prepublishOnly, como estrategia de transición para permitir a los usuarios evitar el comportamiento confuso de las versiones existentes de npm y sólo ejecutar en npm publish (por ejemplo, ejecutar las pruebas una última vez para asegurarse de que están en buena forma).

Vea https://github.com/npm/npm/issues/10074para una justificación mucho más larga, con más lecturas, para este cambio.

Casos de uso

Si necesita realizar operaciones en su paquete antes de que se use, de forma que no dependa del sistema operativo o de la arquitectura del sistema de destino, utilice un script prepublish. Esto incluye tareas como:

• Compilar el código fuente de CoffeeScript en JavaScript.
• Crear versiones minificadas del código fuente de JavaScript.
• Obtener recursos remotos que su paquete utilizará.

La ventaja de hacer estas cosas en prepublish tiempo es que se pueden hacer una vez, en un solo lugar, reduciendo así la complejidad y la variabilidad. Además, esto significa que:

• Puedes depender de coffee-script como un devDependency, y así tus usuarios no necesitan tenerlo instalado.
• No necesitas incluir minificadores en tu paquete, reduciendo el tamaño para tus usuarios.
• No necesitas depender de que tus usuarios tengan curl o wget u otras herramientas del sistema en las máquinas de destino.

Orden de operación del ciclo de vida

npm publish

• prepublishOnly
• prepare
• prepublish
• publish
• postpublish

npm pack

• prepack
• postpack

npm install

• preinstall
• install
• postinstall

También activa

• prepublish (cuando en local)
• prepare (cuando en local)

npm start

npm run start tiene una abreviatura npm start.

• prestart
• start
• poststart

Valores por defecto

npm predeterminará algunos valores de los scripts basándose en el contenido del paquete.

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

  Si hay un archivo server.js en la raíz de su paquete, entonces npmwill predeterminará el comando start a node server.js.

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

  Si hay un archivo binding.gyp en la raíz de su paquete y no ha definido sus propios scripts install o preinstall, npm predeterminará el comando install para compilar usando node-gyp.

Usuario

Si npm fue invocado con privilegios de root, entonces cambiará el uid a la cuenta de usuario o uid especificado por la configuración user, que por defecto es nobody. Establezca la bandera unsafe-perm para ejecutar los scripts con privilegios de root.

Entorno

Los scripts de paquetes se ejecutan en un entorno en el que muchas piezas de información están disponibles con respecto a la configuración de npm y el estado actual del proceso.

ruta

Si usted depende de los módulos que definen los scripts ejecutables, como testsuites, entonces esos ejecutables se añadirán al PATH para ejecutar los scripts. Así, si su package.json tiene esto:

 { 
 "nombre" : "foo", 
 "dependencias" : { 
 "bar" : "0.1.x" 
 }, 
 "scripts": { 
 "start" : "bar ./test" 
 } 
 } 

entonces podrías ejecutar npm start para ejecutar el script bar, que se exporta al directorio node_modules/.bin en npm install.

package.json vars

Los campos de package.json están adheridos al prefijo npm_package_. Así que, por ejemplo, si tienes {"name":"foo", "version":"1.2.5"} en tu archivo package.json, entonces tus scripts de paquete tendrían la variable de entornonpm_package_name establecida como «foo», y lanpm_package_version establecida como «1.2.5». Puede acceder a estas variables en su código con process.env.npm_package_name yprocess.env.npm_package_version, y así para otros campos.

configuración

Los parámetros de configuración se ponen en el entorno con el prefijonpm_config_. Por ejemplo, se puede ver la rootconfig efectiva comprobando la variable de entorno npm_config_root.

Especial: objeto package.json «config»

Las claves package.json «config» se sobrescriben en el entorno sihay un parámetro config de <name>:<key>. Por ejemplo, si el package.json tiene esto:

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

y el server.js es este:

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

entonces el usuario podría cambiar el comportamiento haciendo:

 npm config set foo:port 80 

evento del ciclo de vida actual

Por último, la variable de entorno npm_lifecycle_event se establece en la etapa del ciclo que se está ejecutando. Por lo tanto, usted podría tener una sola secuencia de comandos utilizados para diferentes partes del proceso que switchesbased en lo que está sucediendo actualmente.

Los objetos se aplanan siguiendo este formato, por lo que si usted tenía{"scripts":{"install":"foo.js"}} en su paquete.json, entonces verías esto en el script:

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

Examples

Por ejemplo, si tu package.json contiene esto:

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

entonces se llamará a scripts/install.js para las etapas de instalación y post-instalación del ciclo de vida, y se llamará a scripts/uninstall.jscuando se desinstale el paquete. Dado que scripts/install.js se ejecuta para dos fases diferentes, sería prudente en este caso mirar la variable de entorno npm_lifecycle_event.

Si desea ejecutar un comando make, puede hacerlo. Esto funciona perfectamente:

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

Salir

Los scripts se ejecutan pasando la línea como argumento del script a sh.

Si el script sale con un código distinto de 0, entonces esto abortará elproceso.

Note que estos archivos de script no tienen que ser nodejs o incluso programasjavascript. Sólo tienen que ser algún tipo de archivo ejecutable.

Hook Scripts

Si quieres ejecutar un script específico en un evento específico del ciclo de vida para TODOS los paquetes, entonces puedes usar un script hook.

Coloca un archivo ejecutable en node_modules/.hooks/{eventname}, y se ejecutará para todos los paquetes cuando estén pasando por ese punto en el ciclo de vida del paquete para cualquier paquete instalado en esa raíz.

Los scripts hook se ejecutan exactamente de la misma manera que los scripts package.json, es decir, están en un proceso hijo separado, con el entorno descrito anteriormente.

Mejores prácticas

• No salga con un código de error distinto de cero a menos que lo diga en serio. Si el fallo es menor o sólo impedirá algunas características opcionales, entonces es mejor simplemente imprimir una advertencia y salir con éxito.
• Trate de no usar scripts para hacer lo que npm puede hacer por usted. Lea a través depackage.json para ver todas las cosas que puede especificar y habilitar simplemente describiendo su paquete apropiadamente. En general, esto conducirá a un estado más robusto y consistente.
• Inspeccione el env para determinar dónde poner las cosas. Por ejemplo, si la variable de entorno npm_config_binroot se establece en /home/user/bin, no intente instalar ejecutables en /usr/local/bin. El usuario probablemente lo configuró así por una razón.
• No anteponga a sus comandos de script «sudo». Si se requieren permisos de root por alguna razón, entonces fallará con ese error, y el usuario sudo el comando npm en cuestión.
• No use install. Utilice un archivo .gyp para la compilación, y prepublish para cualquier otra cosa. Casi nunca debería tener que establecer explícitamente apreinstall o instalar el script. Si usted está haciendo esto, por favor considere si hay otra opción. El único uso válido de install o preinstallscripts es para la compilación que debe hacerse en la arquitectura de destino.

Ver también

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