Pasos para crear una librería para NodeJS
February 08, 2017
Probablemente tengas en mente desarrollar una librería para NodeJS. Al final de esta publicación tendrás tu librería publicada en npm. Antes de eso, hablaré un poco de mis proyectos personales. — Hasta ahora he creado siete paquetes para NodeJS, una de esas ha llegado bastante bien en la comunidad de JavaScript, se llama Sails Inverse Model. Una parte de las otras seis librerías fueron creadas para complementar la anterior, el resto solamente realiza operaciones sencillas.
Empecemos… Antes de entrar a ver código es necesario cumplir con otros pasos:
- Crear una cuenta de usuario en npm.js.
- Instalar NodeJS.
- Instalar un editor de código. Quizás te guste Atom, Visual Studio Code o Sublime Text.
- Pasos obvios: Saber JavaScript y usar la consola.
Esta publicación posee un subtitulo muy particular: Creando una librería para generar nombres de gatos. Se trata de una librería existente creada por desarrollador muy conocido, su nombre es Sindre Sorhus (o al menos así se hace llamar). La función de este paquete es mostrar nombres aleatorios de gatos, y la he escogido por su sencillez en el código fuente. También ha creado librerías para generar nombres de perros, súper héroes, pokémones, súper villanos y arboles… Aunque posee una cantidad absurda de librerías, mas de 900 paquetes publicados en npm. :O
En esta guía veremos el funcionamiento del paquete cat names y como programarla. Posteriormente, se hará el proceso de subir este paquete al repositorio de npm.
Paso 1. Crear archivos
Crear una carpeta que contendrá todos los archivos fuente de la librería.
$ mkdir cat-names
Posteriormente debes crear cuatro archivos dentro del directorio “cat-names”:
**index.js — **Aquí va el código que será ejecutado cuando la función require() sea llamada. P.ej:
var cats = require(‘cat-names’);
cli.js — **Si tu librería es una aplicación de consola entonces debes usar este archivo. **No depende de la función “require()” para ser ejecutado, y puede ser usado como cualquier otro programa de consola, p.ej:
$ cat-names --help
El ejemplo anterior se ejecuta desde la terminal, donde cat-names es el llamado de la aplicación a ejecutar, y help es un parámetro. Otro ejemplo similar: “ping 8.8.8.8”, donde ping es el programa a ejecutar y 8.8.8.8 el parámetro.
**package.json — **Contiene toda la información fundamental de nuestro paquete. Aquí se especifica el nombre del paquete, version, descripción, licencia, autor, información del autor, palabras clave, dependencias…
cat-names.json — Listado de nombres de gatos.
Paso 2. Programar paquete
cat-names.json
index.js
Linea 2. Importar librería para generar un valor aleatorio según un vector dado.
Linea 3. Obtiene una lista de nombres de gatos.
Linea 5. Exporta la lista de nombres de gatos.
Linea 6. Obtiene el nombre de un gato usando el paquete uniqueRandomArray.
cli.js
Linea 4. Librería para gestión de parámetros y mensajes en la terminal.
Linea 5. Importar el archivo index.js. Node reconoce por defecto que ./ es index.js
Linea 7 — 19. Mensaje de ayuda para mostrar en la terminal.
Linea 21. Muestra el resultado de la operación solicitada, es decir, devuelve el listado de gatos o un gato aleatorio.
package.json
Descripción de las claves (keys):
- name. Nombre del paquete. Será mostrado en npm.js
- version. Versión del paquete. Es importante mantener una secuencia ordenada (p.ej: 1.0.0–1.0.1–1.0.2–1.0.3…), de esta manera la secuencia aumenta cada vez que se haga una actualización.
- description. Descripción del paquete. Será mostrada en npm.js
- license. Tipo de licencia de software.
- repository. Enlace al repositorio del código fuente. Enlace de Github, Gitlab…
- author. Datos acerca del autor.
- bin. Clave usada para especificar el archivo que se debe ejecutar cuando el paquete se solicite desde la terminal.
- files. Archivos que deben ser seleccionados para subir al repositorio de npm.js.
- engines. Especifica las versiones de node en la que funciona el paquete:
- scripts. Contiene los comandos que se ejecutan en varias ocasiones en el ciclo de vida de su paquete.
- keywords. Palabras clave que describen el paquete. Esto ayuda a que las personas descubran tu paquete cuando buscan en npm.
- dependencies. Especifica las dependencias asignadas a nuestro paquete. Se describe el nombre de paquete junto a un intervalo de versiones.
- devDependencies. Dependencias necesarias para desarrollar el paquete.
Es importante crear el archivo de documentación README.md. Ver ejemplo.
Paso 3. Probar código
En este paso vamos a verificar que nuestro paquete esté funcionando correctamente. Para esto es necesario instalar las dependencias:
# Acceder al directorio
$ cd cat-names
# Instalar paquetes
$ npm install
=> Se muestra todo el proceso de instalación de dependencias
$ node cli.js —help
=> Muestra la ayuda de nuestro paquete
$ node cli.js
=> Muestra el nombre de un gato
$ node cli.js —all
=> Muestra una lista de gatos
Paso 4. Iniciar sesión en NPM
Se exige tener una cuenta de usuario en npm.js
# Iniciar la sesión desde la terminal
$ npm login
= Se solicitan las credenciales (email & password)
Paso 5. (Ultimo) Subir librería a NPM
Ultimo paso. Se carga todo el paquete al repositorio oficial de NodeJS, en instantes quedará disponible públicamente.
$ npm publish
=> Muestra el proceso de carga.
=> Finalmente se muestra el resultado de la operación.
Recomendaciones
- Recuerda aumentar la secuencia de la versión para evitar errores de subida.
- Cada vez que se agregue un nuevo archivo o carpeta es importante referenciarlo en el package.json, dentro de la clave files.
- Es importante escribir toda la documentación que sea necesaria para especificar el funcionamiento de tu paquete. Esto ayudará a que otros usuarios entiendan como instalar y usar tu librería.
- Si quieres dar a conocer tu librería, deberías publicarlo en las redes sociales. Un tweet con los hashtag adecuados puede llegar a muchos usuarios en poco tiempo.
- Recuerda mantener actualizada las versiones de las dependencias. Algunas veces estos se convierten en paquetes obsoletos de un momento a otro.
- Mantener buenas practicas de desarrollo.
Otros ejemplos para ver
Espero que te haya gustado esta guía :). Me gustaría conocer la(s) librería(s) que has desarrollado. Gracias por leer.