Crear un Paquete

Un paquete es un directorio con código que contiene un archivo package.json que provee información a Yarn acerca del paquete.

La mayoría de los paquetes utiliza algún tipo de sistema de control de versiones. El más común es git pero con Yarn no importa cuál hayas seleccionado. Para esta guía, los ejemplos se harán en git.

**Nota: ** Si quieres seguir esta guía. asegúrese de instalar primero git y Yarn.

Creando tu primer paquete

Para crear tu primer paquete, abra el terminal/consola del sistema y ejecute los siguientes comandos:

git init mi-proyecto
cd mi-proyecto
yarn init

Esto va a crear un nuevo repositorio git, entra en él y entonces se inicia un formulario interactivo para la creación de un nuevo proyecto Yarn con las siguientes preguntas:

name (mi-proyecto):
version (1.0.0):
description:
entry point (index.js):
git repository:
author:
license (MIT):

Puedes escribir respuestas para cada de estas preguntas o puedes simplemente dar enter para utilizar el valor por defecto o dejarlo en blanco.

**Tip: ** Si quieres utilizar los valores predeterminados para todo también puedes utilizar el comando yarn init --yes y omitirá todas las preguntas.

package.json

Ahora, debes tener un package.json que luce similar a este:

{
  "name": "mi-proyecto,
  "version": "1.0.0",
  "description": "Descripción de mi proyecto",
  "main": "index.js",
  "repository": {
    "url": "https://example.com/your-username/mi-proyecto",
    "type": "git"
  },
  "author": "Your Name <you@example.com>",
  "license": "MIT"
}

Los campos que ves en el package.json tienen los siguientes significados:

  • name es el identificador del paquete, si vas a publicarlo en un registro global asegúrate de que es un nombre único.
  • version es la versionamiento semantico del paquete, puedes publicar un paquete tantas veces quieras pero usando versiones diferentes.
  • description es un campo opcional pero recomendado que es usado por otros usuarios de Yarn para encontrar y entender tu proyecto.
  • main es usado para definir el punto de entrada de tu código usado por programas como Node.js. Si no especificas ningún punto de entrada, por defecto será index.js.
  • repository es un campo opcional pero recomendado que provee a los usuarios que usan el paquete de la ruta hacia el código fuente del paquete.
  • author es el creador o responsable del paquete. Sigue el formato "Your name <you@example.com> (http://your-website.com)"
  • license son los términos legales del paquete y define el uso permitido del código del mismo.

Cuando ejecutas yarn init, todo lo que esta haciendo es crear este archivo, en el fondo no pasa mas nada. Puedes editar este archivo tanto como quieras.

Campos adicionales

Vamos a ver algunos campos adicionales del package.json que quizás quieras añadir.

{
  "name": "my-new-project",
  "...": "...",
  "keywords": ["cool", "useful", "stuff"],
  "homepage": "https://my-new-project-website.com",
  "bugs": "https://github.com/you/my-new-project/issues",
  "contributors": [
    "Your Friend <their-email@example.com> (http://their-website.com)",
    "Another Friend <another-email@example.com> (https://another-website.org)"
  ],
  "files": ["index.js", "lib/*.js", "bin/*.js"],
  "bin": {
    "my-new-project-cli": "bin/my-new-project-cli.js"
  }
}
  • keywords es una lista de términos que otros desarrolladores pueden buscar para encontrar tu paquete, u otros paquetes relacionados.
  • homepage es un enlace que apunta a los usuarios a una web que los informará sobre el paquete con una introducción, documentación, y enlaces a recursos adicionales.
  • bugs es un enlace para los usuarios que tengan algún problema con el paquete.
  • contributors lista de personas que contribuyen al paquete. Si hay otras personas involucradas en el proyecto, puedes especificarlas aquí.
  • files es una lista de archivos que deben incluirse en el paquete cuando lo publiques. Si no se especifica Yarn incluira todos los archivos.
  • bin es una asignación de comandos de la cli (binarios) para que Yarn cree el paquete cuando lo instale.</0>.

Para una lista completa de todos los campos de package.json y más detalles sobre cada uno de los campos anteriores consulta la documentación de package.json.

Licencias y Open Source

Paquetes de Yarn generalmente se anima a ser código abierto, sin embargo, es importante tener en cuenta que no son intrínsecamente abiertos por simplemente publicarlos.

En orden de código fuente abierto es necesario tener una licencia de código abierto. Hay muchas licencias de código abierto para elegir, aquí van un par de los más comunes:

Si deseas más opciones, puedes obtener una lista más completa aquí.

Cuando se selecciona una licencia de código abierto para tu paquete, asegúrate de agregar un archivo de licencia LICENSE en la raíz de tu paquete con el texto de la licencia y actualizar el campo license de package.json.

Nota: Si no deseas que tu proyecto sea licenciado como un proyecto abierto, debe ser explícito acerca de lo que la concesión de licencias es o si tiene licencia.

Código compartido

Es probable que desees permitir a los usuarios de tu paquete poder acceder a su código fuente y reportar problemas. Hay un par de sitios web populares para hostear tu código:

Estos sitios permiten a los usuarios ver tu código, reportar incidencias y contribuir nuevamente. Una vez que tengas el código en alguno de los anteriores debes agregar los siguientes campos a tu package.json:

{
  "homepage": "https://github.com/username/my-new-project",
  "bugs": "https://github.com/username/my-new-project/issues",
  "repository": {
    "url": "https://github.com/username/my-new-project",
    "type": "git"
  }
}

Documentación

Idealmente deberias escribir tu documentación antes de publicar tu paquete. Como mínimo deberias escribir un archivo README.md en la raíz de tu proyecto que introduzca a tu paquete y documenta la API pública.

Buena documentación se define por dar a los usuarios todo el conocimiento que necesitaran para comenzar con su proyecto y el uso continuado del mismo. Piense en las preguntas que haria alguien que no sabe nada acerca de tu proyecto. Describir con exactitud las cosas y con detalle según sea necesario, pero también trata de mantener que sea breve y fácil de leer. Proyectos con una documentación de alta calidad rinden mucho más.

Mantener los paquetes pequeños

Cuando se crean paquetes Yarn, se recomienda mantenerlos pequeños y simples. Rompe grandes paquetes en muchos pequeños si tiene sentido hacerlo. Esto se recomienda altamente como Yarn es capaz de instalar cientos o incluso miles de paquetes muy eficientemente.

Muchos paquetes pequeños son un gran modelo de gestión de paquetes. A menudo esto conduce a menor tamaño de la descarga porque las dependencias son masivas y sólo usando un pequeño pedazo de la misma.

También deberias considerar el contenido de tu paquete. Asegúrate de que accidentalmente no distribuyes los test o cualquier otro archivo que no es necesario para el uso de tu paquete (construir scripts, imágenes, etc).

También ten cuidado de que paquetes dependes, es preferible dependencias más pequeñas a menos que tengas una buena razón. Asegúrate de que accidentalmente no dependas de algo masivo.