Una guía para npm: el administrador de paquetes de Node.js

JavaScript es fácilmente el lenguaje más utilizado cuando se trata del desarrollo de sitios web y aplicaciones web. La multitud de recursos es asombrosa, y más aún, la cantidad de bibliotecas disponibles.

Al principio, estas bibliotecas son pocas y fáciles de mantener; sin embargo, muy pronto se establece el infierno de la dependencia y se requiere una solución más madura.

Ingrese al Administrador de paquetes de nodos (npm): un administrador de paquetes de JavaScript que se usa principalmente junto con Node.js, aunque también se puede usar de forma independiente. Le brinda un control excepcional sobre las dependencias de su proyecto y proporciona una excelente manera de contribuir al mundo del código abierto.

Puede comenzar simplemente ejecutando npm install <package name> e inyectándolo en su archivo JavaScript.

¿Quieres instalar una versión específica? No hay problema. Ejecute npm install <package name>@1.2.3 .

¿Quiere instalar un paquete globalmente (como Mocha o Angular-CLI)? Simplemente agregue un -g así: npm install -g angular-cli mocha .

Es cierto que la mayoría de los casos de uso se detienen en una instalación de npm y no hay necesidad de nada más. Sin embargo, npm tiene un montón de funciones adicionales, por las que te guiaré, destacando aquellas que considero esenciales, realmente útiles o simplemente geniales.

Comandos CLI

La CLI es donde los usuarios pasan la mayor parte de su tiempo interactuando con npm, y su interfaz de ayuda es realmente útil.

Consultar ayuda ( npm help ) arroja una gran variedad de opciones, y ejecutar npm help-search <searchText> le brinda una lista de resultados de búsqueda directamente desde el descuento de npm.

Estos son los comandos principales que se destacan.

• install : se menciona aquí debido a su absoluta necesidad cuando se trabaja con npm. Se usa para instalar un nuevo paquete local o globalmente (al agregar -g ) o para instalar las dependencias enumeradas en el archivo package.json (más sobre esto más adelante).

• uninstall : Esto también es esencial. Se usa para purgar un paquete específico del directorio node_modules , ya sea local o globalmente (al agregar -g ).

• access : este es el campo de juego de los administradores de permisos de usuario de npm dentro del contexto npm-organizations y paquetes (privados) de alcance. Cosas seriamente poderosas. Usado junto con adduser , owner , team , etc., brinda un control detallado sobre quién tiene acceso a qué.

• bin : ¿Dónde diablos se instalan los paquetes? Ejecute este comando para ver la ruta de archivo absoluta.

• cache : si comienza a instalar paquetes desde npm a la izquierda, a la derecha y al centro, este comando es bastante útil. O llámelo con el subcomando ls para ver una lista de paquetes en caché local o con el subcomando clean para borrar todos los paquetes que están en el caché. Antes, cuando el registro de npm todavía era un poco inestable, esto era esencial para volver a un entorno estable o para restablecer las cosas cuando no configuraba correctamente los permisos de npm.

• config : veremos las diferentes opciones de configuración más adelante, pero este comando se ocupa principalmente de las propiedades de configuración persistentes en el archivo de configuración local o global mediante el uso de los subcomandos set , get o delete .

• dedupe o ddp : cuando se trabaja en un proyecto durante un período extenso de tiempo y se instalan paquetes directamente desde npm, este comando recorrerá el árbol de paquetes local e intentará simplificar las dependencias.

• link : cuando está desarrollando su propio paquete npm, esto le permite crear un enlace simbólico al contexto global para que pueda probarse como si estuviera instalado globalmente desde el registro npm. Por ejemplo, si está escribiendo una herramienta de ensamblaje en un nodo que tiene una CLI instalada globalmente, puede ejecutar este comando y probar el comportamiento de su CLI sin necesidad de implementarla primero.

• ls : se utiliza para visualizar las dependencias de los paquetes y sus dependencias, en una estructura de árbol. Es genial verlo y también es útil para compararlo con otros proyectos.

• outdated : Esto se usa para evaluar el estado actual de las dependencias instaladas y si están desactualizadas o no. En proyectos donde la lista de dependencia raíz tiene cientos de líneas, una verificación manual de los paquetes es casi imposible. Agregar -g --depth=0 a este comando le permite verificar también sus paquetes instalados globalmente.

• publish : este comando es esencial al desarrollar su propio paquete para npm. Hace exactamente lo que sugiere el nombre; publica su paquete en el registro npm.

• search : use esto para buscar en el registro todos los paquetes que contengan el texto proporcionado en el tercer argumento.

• shrinkwrap : en resumen, este comando le permite bloquear versiones de dependencia específicas en un paquete en orden, de modo que un número relajado de semver (versiones semánticas) no rompa el código de producción.

• star : ¿Realmente te gusta un paquete que estás usando? Use este comando para mostrar su agradecimiento directamente desde la terminal, que luego se refleja en la página del paquete en el registro npm.

• update : esto generalmente sigue al comando outdated para actualizar cualquier paquete desactualizado.

• version : Esto le brinda una forma abreviada de mejorar la propiedad de versión de package.json y hacer una etiqueta git, todo en uno.

Tenga en cuenta que la mayoría de estos comandos pueden tomar subcomandos y/o configuraciones, y esta lista de ninguna manera es una discusión final sobre la CLI.

npm-config

La configuración es una parte importante de npm, y hay varias formas en que se pueden establecer las variables de configuración.

Configuración a través de CLI y variables ambientales

Primero, la configuración se puede establecer a través de la CLI desde el terminal.

Por lo general, se vería así: npm <command> --<configuration option> [<optional value>] .

Si no se especifica el valor, la opción se establecerá en verdadero de forma predeterminada.

Por ejemplo, supongamos que está trabajando en un paquete npm con ámbito (privado) y decide publicarlo como un paquete público.

Esto se hace fácilmente agregando --access=public a su comando de publish . Si no especificamos que la propiedad sea pública, el valor predeterminado sería restringido (privado).

La configuración adjunta a otros comandos como este no persiste en todas partes, por lo que puede resultar tedioso establecer una serie de configuraciones a través de la CLI.

En esos casos, puede ser mejor establecer la configuración usando variables ambientales.

Cualquier variable ambiental configurada con el prefijo npm_config_ se usará para configurar npm.

Por ejemplo: export npm_config_registry=localhost:4321 establecería la opción de configuración del registro globalmente y, cuando se ejecute npm, usará el registro npm ubicado en localhost en el puerto 4321.

Configuración a través del archivo npmrc

También puede establecer las opciones de configuración utilizando el archivo especial .npmrc , que se puede establecer en diferentes niveles según sus requisitos:

• Nivel de proyecto: en la raíz del código de un proyecto junto con su archivo package.json , normalmente path/to/project/.npmrc
• Nivel de usuario: el directorio que configura la cuenta de un usuario específico, normalmente ~/.npmrc
• Nivel global: el directorio donde npm busca configuraciones globales, generalmente $PREFIX/etc/npmrc
• Nivel incorporado: tenga cuidado. Esta configuración no solo es global, sino que también es parte del código fuente de npm, y las mejores prácticas recomiendan (en realidad exigen) que no cambiemos el código que no somos responsables de mantener. Por lo general, se puede encontrar en /path/to/npm/npmrc .

Los ajustes de configuración en el archivo .npmrc se pueden modificar y conservar mediante la CLI ejecutando un comando en este formato: npm config set <key> <value> .

Por ejemplo, puede ejecutar npm config set access public para hacer que la configuración de publicación de un paquete con ámbito (privado) sea pública de forma persistente.

De forma predeterminada, este comando conservaría la configuración localmente (la configuración de nivel de usuario como se describe anteriormente), pero puede agregar -g para conservarla globalmente.

Cuando es necesario realizar una configuración persistente en el nivel del proyecto o en el nivel integrado, el archivo .npmrc debe modificarse con un editor de texto.

Configuración a través de package.json

Finalmente, la configuración se puede establecer desde el archivo package.json . Sin embargo, esto rara vez se usa (y solo debe usarse si se requiere explícitamente), porque un archivo .npmrc a nivel de proyecto es el lugar preferido convencionalmente para establecer la configuración del paquete.

Ajustes de configuración notables

• access : como se discutió anteriormente, se usa para establecer permisos.

• always-auth : es importante tener en cuenta que esta configuración predeterminada es falsa. Cuando se establece en verdadero, npm siempre requerirá autenticación cuando se comunique con el registro.

• ca : el valor predeterminado es la autoridad de certificación (CA) de npm. Se puede cambiar a nulo para permitir el acceso solo a registradores conocidos, o a un certificado de CA específico para otorgar acceso solo a ese específico. Esta configuración, junto con cafile , cert y strict-ssl , rara vez se usa, pero habla del aspecto de seguridad y confiabilidad de npm, lo que le permite tener la tranquilidad de saber que el paquete que está instalando proviene de la fuente que espera.

• color : el valor predeterminado es verdadero, lo que le brinda un descanso de la desolación estándar de la terminal al colorear la stdout estándar permitida por los descriptores de archivos tty. Si se establece en falso, el terminal permanece aburrido. Cuando se establece en always , siempre emite en color.

• depth : esta configuración permite un control granular sobre lo que ve con comandos recursivos, como ls y outdated , al asignar la profundidad con la que se ejecutan. Un valor de 0 solo evaluará el primer nivel de dependencias, mientras que infinito (el valor predeterminado) hará que se evalúen todos los niveles de dependencias. La excepción a esta regla es cuando se usa con outdated ; en ese caso, el infinito se interpreta como 0 para garantizar una salida más relevante.

• dev : esto se establece en falso de forma predeterminada, pero cuando se establece en verdadero (al realizar una instalación de npm install ), todas las dependencias de desarrollo en el archivo package.json se instalarán junto con las dependencias normales.

• dry-run : cuando esta configuración se establece en verdadero, npm no realizará ningún cambio en su paquete, sino que le dirá lo que habría hecho. Esto puede ser muy útil cuando se ejecutan ciertos comandos, como dedupe o update .

  

• git-tag-version : se establece en verdadero de forma predeterminada. Esta configuración etiqueta una versión en git cuando se ejecuta el npm version . Si está utilizando npm como administrador de paquetes para un proyecto grande que tiene versiones etiquetadas en git, puede ahorrarle tiempo y recuerde actualizar el archivo package.json por usted.

• loglevel : de forma predeterminada, se establece en warn , lo que genera un error y una salida de advertencia cuando se ejecutan comandos npm. Otras configuraciones incluyen silent , que no proporciona salida; error , que solo registra errores en la salida; http , que solo anuncia errores de solicitud de http; info , para querer salida informativa); verbose , que registra casi todo; y silly , que, como sugiere el nombre, da una cantidad tonta de salida y algo más.

• production : cuando se establece en verdadero, npm actúa en consecuencia y ejecuta todos los comandos en modo de producción. Esto significa que no se instalarán dependencias de desarrollo u opcionales, ni se ejecutará ninguna tarea relacionada con el desarrollo.

• rollback : cuando se establece en verdadero, se eliminan todas las instalaciones fallidas. Esto es útil cuando falla una instalación de dependencias. Dependiendo de su nivel de registro, debería poder ver qué instalaciones fallaron, anotarlas y ejecutar el comando npm install con la opción de reversión establecida en verdadero. Luego, con sus notas y una instalación de ejecución en seco (como se describe anteriormente), puede depurar el problema.

• guardar : When installing a package directly from the registry, you can append -save to the command which will add the installed package to the dependencies option in the file. For example, file. For example, npm install lodash` agregará lodash a sus dependencias.

• save-dev : similar a la opción de guardar configuración, agregue --save-dev al instalar un paquete y luego se agregará a la opción devDependencies en el archivo package.json .

• save-optional : similar a la opción de guardar configuración, agregue --save-optional al instalar un paquete, y luego se agregará a la opción de dependencias opcionales en el archivo package.json .

• save-exact : al instalar paquetes, las opciones save , save-dev y save-optional modifican el archivo package.json insertando el paquete instalado en su propiedad respectiva con un operador de rango semver. Cuando se invoca la opción de configuración 'guardar exactamente' con un valor de verdadero, junto con una de las opciones mencionadas anteriormente, se usa un número de versión específico, ignorando el rango de semver.

• save-prefix : Esto establece el operador de rango semver cuando se usa save , save-dev o save-optional . El valor predeterminado es ^ , lo que permite que se realicen actualizaciones menores en los paquetes durante la instalación. Esto se puede establecer en cualquier operador de rango de semver con prefijo válido.

• tag-version-prefix : el valor predeterminado convencional es v , que especifica lo que se antepone a la versión de la etiqueta git cuando se ejecuta npm version .

Actualización de npm Uso de npm

También puede usar npm para actualizarse.

Simplemente ejecute npm install -g npm@latest y npm se actualizará a la última versión estable. Es importante tener en cuenta que cada versión de Node.js se envía con una versión específica de npm y, según mi experiencia, no debe meterse demasiado con esa combinación.

Al final del día, mi recomendación es seguir con el emparejamiento tal como está previsto.

Cuando use npm como una herramienta independiente, asegúrese de comprender las implicaciones de usar cualquier versión que elija. Hay una gran herramienta para administrar diferentes versiones de Node.js (y, a su vez, versiones de npm) en el mismo sistema llamado nvm.

El archivo paquete.json

El archivo package.json es el elemento crucial que une todo.

Es un requisito para publicar un paquete en el registro npm, y es donde cobra vida la parte de administración de las dependencias.

Tiene dos campos obligatorios, a saber, "nombre" y "versión", y juntas estas propiedades deben ser un identificador único.

El campo de nombre debe cumplir ciertas reglas, tal como se define en la documentación de npm sobre nombres, y el campo de versión está sujeto a las especificaciones del servidor.

Más allá de eso, puede tener una lista de dependencias de una milla de largo y definir una versión específica que se usará para cada una de ellas, utilizando las versiones de semver y los operadores de rango. Aquí hay una lista de otras propiedades notables.

"principal"

“main” define el punto de entrada a su aplicación, que por defecto es index.js . Según la convención o su marco, podría ser app.js o main.js Por supuesto, puedes convertirlo en lo que quieras.

"guiones"

Esta es una propiedad subestimada.

En primer lugar, se puede utilizar para hacer cosas en prepublicación.

En segundo lugar, proporciona un lugar donde puede crear un alias para una serie de comandos de uso frecuente, que van desde tareas de compilación (definidas en gulp o grunt), desencadenar la instalación de otras dependencias (con algo como Bower), iniciar un servidor de desarrollo con webpack o ejecutando un conjunto de comandos bash.

"dependencias"

Esta propiedad es una lista de paquetes que necesita su aplicación, junto con el número de servidor compatible. Es una propiedad notable porque se puede modificar desde la terminal cuando instala paquetes locales.

Esto se hace agregando --save (o la abreviatura -S ) al final del comando npm install .

Cuando hace esto, los paquetes recién instalados se agregan a la lista de dependencias en su archivo package.json .

Del mismo modo, también se puede eliminar una dependencia agregando --save al ejecutar el npm uninstall .

Es importante conocer los patrones de versiones de semver de cada una de las dependencias y lo que significan.

Si la regla semver es demasiado estricta, se pierden nuevas características y mejoras, mientras que si la regla semver es demasiado relajada, se puede instalar una versión innovadora de un paquete a lo largo de la línea.

La instalación de un paquete roto puede resultar bastante difícil de resolver, especialmente cuando se usa la versión minimizada del paquete.

"Dependencias de desarrollo"

Aparte de la propiedad de dependencias, la propiedad "devDependencies" le permite definir dependencias que solo se usan durante la fase de desarrollo y no son necesarias para la compilación de producción (como ESLint, paquetes grunt-contrib y Protractor). Al igual que con las dependencias, esta propiedad se puede modificar desde la terminal agregando --save-dev (o la abreviatura -D ) al final del comando npm install o el comando npm uninstall . La misma precaución se aplica al control de versiones como se menciona en las dependencias.

"compartimiento"

Aquí es donde puede especificar los archivos ejecutables de su paquete, como la ruta a una utilidad CLI. Esta propiedad le dice a npm que cree enlaces simbólicos locales o globales a sus ejecutables cuando se instala su paquete.

"configuración"

Como se discutió anteriormente, aquí es donde define los ajustes de configuración a través de su archivo package.json .

"privado"

Cuando se establece en verdadero, npm se negará a publicar el paquete.

Esto no debe confundirse con la opción de configuración de acceso.

Esta es una configuración útil cuando tiene un proyecto que utiliza npm junto con su package.json , pero no está diseñado para publicarse en el registro de npm, ya sea con alcance o público.

Si su intención cambia, simplemente cambie la configuración a falso y podrá publicar su paquete.

Propiedades personalizadas

El archivo package.json también acepta propiedades personalizadas, siempre que el nombre no esté ya definido o reservado.

Desarrollo de su propio paquete npm

El ecosistema npm está repleto de paquetes, escritos por miles de desarrolladores diferentes en todo el mundo. Cada uno resuelve algún tipo de problema, proporcionando una abstracción o presentando una implementación de algo.

Lo más probable es que, en algún momento, usted también desee desarrollar su propio paquete para compartir.

Primero, debe crear un archivo package.json con las propiedades mínimas requeridas de "nombre" y "versión", y luego la propiedad "principal" para especificar el punto de entrada, por ejemplo, index.js.

Escriba su código en ese archivo index.js, inicie sesión con su cuenta de usuario de npm o cree un nuevo usuario desde la terminal y estará listo para publicarlo en el registro de npm.

Los paquetes pueden ser públicos o privados.

Los paquetes públicos son gratuitos para publicar y están disponibles para que todos los utilicen.

Los paquetes privados, llamados paquetes con ámbito, solo se pueden publicar si pagó como usuario de módulos privados, y se pueden identificar por el distintivo @username/ que se antepone al nombre del paquete.

Los paquetes con ámbito también se pueden publicar públicamente llamando al comando de publish con --access=public .

Además, si pasa más tiempo expandiendo y mejorando el código base de su paquete, y es hora de que se publique una nueva versión, simplemente modifique la versión (según las reglas y convenciones de semver) del paquete en el package.json archivo y escriba npm publish .

También puede usar la interfaz de línea de comandos y llamar a npm version <update_type> , donde update_type es patch , minor o major , como lo describe semver, y luego incrementa automáticamente el número de versión en el archivo package.json .

Organizaciones npm

Nuevamente, la documentación de npm para esto es excelente, y sería inútil repetir sus palabras.

Lo que se puede decir acerca de las organizaciones en el contexto de npm es que es extremadamente detallado y, cuando se administra correctamente, los equipos grandes y las personas que trabajan en paquetes públicos o de alcance bajo un nombre pueden administrarse y restringirse muy bien.

Si bien es complejo de dominar, es muy gratificante.

El poder de npm

En última instancia, la documentación que proporciona npm es extensa y debe consultarse para obtener información específica, pero este artículo proporciona una descripción general útil de la funcionalidad involucrada, tanto básica como más avanzada, que transmite la genialidad de npm.

Como con todas las cosas, existen opiniones fuertes y se pueden encontrar muchas fallas. Pero si nunca ha probado npm (o node, para el caso), sumérjase y explórelo usted mismo. Lo más probable es que lo disfrutes más de lo que piensas.

Para obtener más artículos interesantes sobre npm, considere leer Uso de Scala.js con npm y Browserify.