Node.js / usando npm

Bienvenidos sean a este post, hoy hablaremos nuevamente sobre npm.

En este post vimos como utilizar basicamente el npm para poder instalar un paquete, dado que actualmente el mismo se instala en conjunto con node.js, pero hoy nos centraremos en ver mas especificamente algunos conceptos mencionados en el post anteriormente citado.

Formato del paquete npm

Basicamente es muy similar a lo visto anteriormente pero la unica diferencia es que npm utiliza y reconoce mas campos que node.js, su formato es definido por las especificaciones del Paquete de CommonJS 1.0 y si necesitan ver mas sobre su documentacion, simplemente usen este comando:

$ npm help package.json

A continuacion les dejo un ejemplo basico de un archivo:

{ "name": "nombrePaquete", 
   "version": "1.0", 
   "main": "nombreModuloPpal",
   "bin": "./path/al/programa"
} 

Como mencionamos anteriormente npm reconoce mas campos que estos pero sobre ellos hablaremos a medida que avanzemos con algunos temas, pasemos al siguiente tema.

Obteniendo ayuda

En el tema anterior mencionamos un comando para obtener la documentacion sobre package.json pero este nos permte obtener mas informacion sobre las distintas acciones que podemos ejecutar con npm, para ello deben hacerlo de la siguiente manera:

npm help <comando>

Donde comando sera el identificador para obtener mas documentacion sobre el mismo, les dejo un ejemplo:

$ npm help install

Con todo esto comentado podemos pasar al siguiente tema.

Nota:
Si necesitan un listado de los comandos disponibles simplemente escriban npm para obtenerlo.

Iniciando un paquete

Esta herramienta nos permite iniciar un directorio como paquete, por lo visto en posts anteriores sabemos que un paquete como minimo debe tener un archivo json y una serie de archivos de node.js, tambien que este proyecto en muchos casos no debe exportar ninguna funcionalidad sino que es una aplicacion, asi que tambien puede necesitar de otros proyectos, y esto debe estar dentro del archivo package.json lo cual nos facilitara la instalacion mediante npm.

Aunque esto no quita que pueda usarse para distribuir funcionalidad y este sea utilizados por otros proyectos o aplicaciones, pero igualmente consistiran de un archivo package.json y algunos archivos de node.js pero en lugar de ejecutarlo lo incorporaremos mediante require,, import o import(), de los cuales hablamos en el post anterior, con esto podemos decir que la clave para crear un paquete es el archivo json, y si bien este podemos crearlo a mano la herramienta nos provee una opcion para poder crearlo por nosotros, veamos un ejemplo:

Este es un ejemplo simple de como se puede completar, observen que en algunos casos usamos los valores predeterminados, en otros los completos y algunos los dejamos en blanco, en este caso nos hara el archivo base donde despues agregaremos los demas campos que vayamos necesitando, como las dependencias por citar un ejemplo, pasemos al siguiente tema.

Buscando paquetes

Para buscar paquetes tenemos dos formas, la primera es mediante la pagina:

https://www.npmjs.com/

Donde simplemente lo buscaremos y despues mediante npm install lo instalaremos o podemos hacerlo mediante el siguiente comando:

npm view <nombre_paquete>

Donde nombre_paquete sera el nombre del mismo, tomemos el siguiente ejemplo:

$ npm view prompt

Este nos devolvera toda la informacion sobre este paquete:

$ npm view prompt

prompt@1.3.0 | MIT | deps: 5 | versions: 38
A beautiful command-line prompt for node.js
https://github.com/flatiron/prompt#readme

keywords: prompt, command-line, customize, validation

dist
.tarball: https://registry.npmjs.org/prompt/-/prompt-1.3.0.tgz
.shasum: b1f6d47cb1b6beed4f0660b470f5d3ec157ad7ce
.integrity: sha512-ZkaRWtaLBZl7KKAKndKYUL8WqNT+cQHKRZnT4RYYms48jQkFw3rrBL+/N5K/KtdEveHkxs982MX2BkDKub2ZMg==
.unpackedSize: 137.0 kB

dependencies:
@colors/colors: 1.5.0 read: 1.0.x           winston: 2.x
async: 3.2.3          revalidator: 0.1.x

maintainers:
- fedor.indutny <fedor.indutny@gmail.com>
- jcrugzz <jcrugzz@gmail.com>
- indexzero <charlie.robbins@gmail.com>
- bradleymeck <bradley.meck@gmail.com>
- caub <cyril.auburtin@gmail.com>

dist-tags:
latest: 1.3.0

published a year ago by caub <cyril.auburtin@gmail.com>
$

En cambio si lo ejecutamos de la siguiente forma nos devolvera el archivo json completo del paquete:

$ npm view prompt --json

Por otro lado, tomando lo visto anteriormente al momento de iniciar un paquete y buscarlo mediante view debemos tener como minimo los siguientes campos bien confeccionados:

• name, es el nombre del paquete
• descripcion, la mejor, breve y concisa descripcion del paquete
• keywords, palabras claves que faciliten su busqueda

Tambien es util agregar un archivo README.md donde agregaremos mas informacion sobre nuestro paquete pero esta pensado principalmente para la pagina mencionada anteriormente,, pasemos al siguiente tema.

Instalando un paquete

Esto ya lo hemos realizado en posts anteriores y lo hemos comentado en este post, veamos su sintaxis mas basica:

npm install <nombre_paquete>

Esto podemos denominarlo como instalacion local porque instalara el paquete dentro del nuestro, en cambio si queremos hacerlo de forma global debemos agregar la siguiente opcion:

npm install -g <nombre_paquete>

Esto hara que se instale por fuera de nuestro proyecto pero esto no es recomendable dado que si queremos distribuirlo deberemos agregar un instructivo de como instalar e implementarlo y no simplemente pasarlo, dando mayor probabilidades de error a la hora de implementarlo, por eso se prefiere hacerlo localmente, pero suponiendo que igualmente queremos instalarlo globalmente, este donde se guardara? bueno, este siempre estara en:

PREFIX/lib/node_modules

Ahora la pregunta es como averiguamos el valor de PREFIX? para ello tenemos el siguiente comando:

$ npm config get prefix

El cual nos devolvera la ubicacion almacenada en PREFIX, veamos en mi caso:

$ npm config get prefix
/usr
$

Este valor puede variar dependiendo de la distro que esten usando, otra posibilidad que disponemos es instalar por versiones pero para ello deberemos tenerla declarada en el archivo json, veamos un ejemplo:

{ ...
  "version": "1.2.1",
  "dist-tags-": {
    "latest": "1.2.1"
  },
... }

Este es un ejemplo basico, donde tendremos la version y en dist-tags la ultima de este paquete, una ventaja que disponemos es que podemos hacer un mantenimiento simple de este ultimo mediante el comando npm dist-tags, pero para instalar por versiones tenemos varias opciones disponibles:

• npm install nombre_paquete@tag
• npm install nombre_paquete@version
• npm install nombre_paquete@rango-version

La primera opcion le pasamos el tag del archivo json, las otras dos son con el valor de la version en el primer caso podemos usar este:

$ npm install ejemplo-paquete@1.2.1

En este caso le especificamos cual es la version del paquete que deseamos instalar, el otro caso es este:

$ npm install ejemplo-paquete@"< 1.0.2"

$ npm install ejemplo-paquete@">= 1.0.1 < 1.1.9"

En el primer caso instalara la version o versiones que esten por debajo de la indicada, y en el segundo caso instalara la o las versiones indicadas en el rango, pero tambien podemos instalarlo por fuera del repositorio.

En algunas ocasiones puede suceder que no todos los paquetes estan en el repositorio sino que son de algunos grupos que no pueden compartirlo de esta manera pero lo bueno es que npm nos permite especificar una direcion desde donde descargarlo, para especificar la direccion podemos hacerlo de la siguiente forma:

• URL, se especifia una url que apunte a un tarball, tanto GitHub como GitLab nos pueden proveer uno muy facilmente
• Git URL, similar al anterior porque cualquier repositorio puede accederse manera sencilla

De este ultimo caso podemos usar un ejemplo como el siguiente:

$ npm install git+ssh://usuario@hostname:proyecto.git#git-tag

Enlistemos las distintas posibilidades:

• Acceso a GitHub, en este caso podemos pasar el especificador del repositorio directamente
• Accesos a GitLab, BitBucket y GitHub, en adicion al caso anterior podemos pasar los siguientes:
  – github:user/repo
  – bitbucket:user/repo
  – gitlab:user/repo
• archivos locales, tambien podemos hacerlo desde un directorio mediante la url:
  file:../path/al/dir

Con esto hemos completado varias formas de poder instalar los paquetes, pasemos al siguiente tema.

Manejando dependencias con npm

De manera inicial podemos decir que disponemos de dos herramientas, si usamos a npm install sin indicar un paquete este nos instalara todas las dependencias en el archivo package.json, por otro lado npm update toma todas las dependencias de los paquetes instalados y los compara contra los repositiorios de npm y cuando encuentra alguno desactualizado procede a actualizarlo.

Estas dos herramientas nos facilitan mucho la tarea porque el creador solo debe listar las dependencias y npm hara el resto pero tambien podemos hacerlo de forma manual, ya sea editando el archivo json manualmente o bien mediante el siguente comando:

$ npm install ejemplo-paquete --save

La opcion del final hara que se agregue el tag dependencies en el archivo json:

"dependencies": { 
    "ejemplo-paquete": "^1.2.1" 
} 

Por lo tanto de ahora en mas cada vez que lo instalemos lo hara junto a esta dependencia, pero tambien disponemos de las devDependencies que son los modulos utilizados en desarrollo y testing, para esto en lugar de usar la opcion anterior debemos usar –save-dev, este es ideal para los casos donde usamos modulos de tipo global, y de manera predeterminada npm install instalara ambas dependencias pero en caso de necesitar solo las de «produccion» al momento de instalarlo podemos usar la siguiente opcion:

$ npm install --production

Este instalara solamente los modulos en dependecies, omitiendo el resto, por ejemplo si el proyeccto tiene instalado a babel con esto lo omitiremos dado que deberia ser solo para el entorno de desarrollo.

Pero a partir de la version 5 de npm ya no es necesario la opcion de –save para agregar una nueva dependecia dado que ahora npm lo hace de manerra predeterminada, facilitando nuestra tarea, y si bien puede resultar inconveniente podemos desactivarla medainte el sigueinte comando:

$ npm config set save false

Esto equivaldria a hacer –no-save, pero uno de los propositos de hacer una correcta admminstracion de las dependencias es para corregir errores o bugs.

Los errores pueden ocurrir por cualquier situacion, ya sea por una actualizacion de un modulo, una aplicacion tuya dispara un error, o alguna otra pero en todo caso simplemente debemos actualizar a la ultima version (o una anterior) de la depencdenccia en cuestion.

Lo esencial en todo caso es identificar cual es el paquete con el inconveniente, si es uno externo averigua si los encargados lo solucionaron, si en cambio este se encuentra «hosteado» en un lugar publico (p.e. GitHub) mira si no existe un «issue» abierto y si tiene alguna posible solucion, una solucion rapida es como dijimos antes usar una version anterior, para ello vamos a suponer que la version 1.2.1 introdujo un bug y no sabemos como solucionarlo pero la version 1.1.9 sabemos que funciona perfectamente, para ello vamos al archivo package.json y cambienos las dependencias de la siguiente manera:

"dependencies": { 
    "ejemplo-paquete": "1.1.9" 
} 

Con esto sabemos que ahora el bug esta solucioando y nos dara algo de tiempo para poder corregirlo, otro consejo que tambien puedo darles es ser especifficos con las versiones de dependencias, evitan usar un asterisco (*) para que no sea cualquiera y sobre todo traten de que nuestro package.json automatice lo maximo posible la instalacion de nuestro paquete, con esto comentado veamos el sigueinte tema.

Instalando comandos

Una cosa que mencionamos en otros posts es la posibilidad de instalar paquetes que nos agregan comandos que nos pemiten interactuar con el shell script, como hexy o babel, en este caso siempre se recomienda fuertemente que se declaren correctamente en package.json, se instalen localmente y a su vez se declare en la variable PATH del entorno del S.O, esta variable es compartida por Linux y Windows, como mencionamos con otros modulos se puede instalar de la siguiente forma:

• global, este se instalara en el directorio donde este instalado node.js pero este variara dependiendo de la distro, pero rara vez se debe modifficar el PATH para agregarlo al mismo
• local, se instala dentro de la aplicacion, queda lista para ser usada por la misma y agregar al PATH se debe hacer manualmente.

Pero porque agregarla al PATH cuando se instala de forma local? bueno el tema es mas que nada para ejcecutarlo sin tener que usar el path del comando, por ejemplo:

./node_modules/.bin/hexy package.json

no es algo muy comodo para utilizar en cambio si lo agregamos al path podemos usarlo asi:

hexy package.json

Para poder agregarlo al PATH en Unix/Linux deben usar uno de los siguientes comandos:

$ export PATH=./node_modules/.bin:$PATH     # bash
$ setenv PATH ./node_modules/.bin:$PATH     # csh

Esto es para dos tipos de terminales, en cambio para Windows deben hacerlo a traves de la terminal o mediante las Propiedades de Mi Pc o Este Equipo, Configuracion avanzada del sistema en las variables de entorno

Con esto ya hemos terminado este tema, pasemos al siguiente.

Actualizando paquetes desactualizados

Una consecuencia de la instalacion de paquetes es que eventualmente se desactualizan, pero tenemos forma de averiguarlo:

$ npm outdated

Este nos devolvera el listado de todos los paquetes desactualizados, y aqui tenemos un comando pero dos opciones:

$ npm update <nombre_paquete>

Este solo actualizara el paquete que le pasemos, en cambio el siguiente:

$ npm update

Este actualizara todos los paquetes dessactualizados, esto deberan utilizarlo dependiendo de la necesidad del momento, pasemos al siguiente tema.

Automatizando tareas con scripts

Una particularidad de npm es que entre todas las acciones que dispone podemos automatizar tarea relacionadas al proyecto, para ello en package.json debemos agregar un campo llamado scripts donde podemos guardar varios tag con cadenas de comando, dado que originalmente fueron pensadas para manejar tareas relacionadas con la instalacion de la aplicacion, pero se terminaron para usar de muchas otras formas, veamos el siguiente ejemplo:

{ ...
  "scripts: {
    "deploy": "rsync --archive --delete local-dir usuario@host:/path/al/dir-dest
  }
... }

En este caso tenemos una tarea de deployment mediante rsync donde copiaremos archivos a un servidor, para ejecutarlo simplemente debemos usar el siguiente comando:

$ npm run deploy

Con solo tenerlo en scripts y mediante el run lo ejecutaremos, como pueden ver es muy simple pero tambien podemos definir un patron pra scripts para correr antes o despues de otro script, simplemente nombrandolo pre o post al nombre de script, por lo tanto el script pretest corre antes del script test y el script posttest correra despues, veamos un ejemplo practico:

{
  "scripts": {
      "test": "cd test && tincho",
      "prepublish": "npm run test"
  }
}

En este tenemos uno llamado test y otro prepublish el cual ejecutara el script anterior, y este se ejecutara antes de usar el siguiente comando:

$ npm publish

Antes de ejecutarlo aplicara el test y usara la palabra tincho para aplicar el suite correcto de test, pasemos al penultimo tema.

Declarando compatibilidad de version

Uno de los principales cuidados que debemos tener es la correcta version de node.js para que todas nuestras caracteristicas funcionen correctamente, para ello debemos utilizar el archivo package.json y aqui usaremos el campo engines, veamos un ejemplo:

"engines": { 
    "node": ">= 8.x <=10.x" 
} 

En este caso tenemos a node y el rango que le pasamos establecera que la aplicacion solo correra con las versiones 8, 9 y 10 de node.js, tengan en cuenta lo que comentamos anteriormente donde pasar las versiones correctas nos garantizan el correcto funcionamiento, pasemos al ultimo tema.

Publicar un paquete

Tambien existe la posibilidad de poder subir al repositorio de npm nuestros propios paquetes, para ello podemos usar al comando npm adduser para registrarnos en los repositorios o bien registrarnos mediante la pagina mencionada al comienzo, despues de registrado por cualquier de los dos medios nuestro siguiente paso sera ingresar mediante npm login, y para finalmente subirlo debemos ir al directorio raiz de nuestro paquete y ahi ejecutaremos el comando npm publish el cual se encargara de subirlo.

En resumen, hoy hemos visto ccomo usar al npm, desde simple comandos hasta como publicar un paquete y otras caracteristicas propia de la herramienta, espero les haya sido de utilidad sigueme en tumblr, Twitter o Facebook para recibir una notificacion cada vez que subo un nuevo post en este blog, nos vemos en el proximo post.