El archivo package.json

El índice con la información de nuestro proyecto


Al crear un nuevo proyecto con npm init, se lanzará un asistente que tras algunas preguntas, crea un archivo llamado package.json en la carpeta raíz del proyecto, donde coloca toda la información que se conoce sobre el mismo. Este archivo es un simple fichero de texto, en formato JSON que incorpora a través de varios campos información muy variada.

Este fichero tiene una estructura definida muy concreta, y a través de sus campos se puede guardar y recuperar información muy útil.

Campos del package.json

Si creamos un nuevo proyecto con los valores por defecto (omitiendo el asistente) con el comando npm init -y, se generará el siguiente archivo package.json, el cuál podemos abrir con nuestro editor de texto preferido para modificarlo:

{
  "name": "frontend-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Por defecto, obtendrá el nombre de la carpeta del proyecto (recuerda que es importante utilizar minúsculas y guiones en lugar de espacio) y nos colocará la versión 1.0.0 por defecto.

Recuerda que el campo name no debe empezar por punto, guión bajo ni debe tener el mismo nombre que otro paquete que uses como dependencia. Una buena recomendación es que se utilice un prefijo/scope como namespace, del tipo @author/nombre-paquete.

Veamos algunos de los campos más habituales de package.json que debemos conocer:

TipoCampoDescripción
nameNombre del proyecto, librería o paquete. Se recomienda que coincida con el repositorio.
versionVersión del paquete. Generalmente se utiliza semver (lo veremos más adelante).
descriptionDescripción breve del paquete o proyecto.
typeTipo de sistema de módulos a utilizar. Con module usa ESM, en caso contrario usa CommonJS.
mainPunto de entrada del proyecto. Suele ser index.js (node) o index.html (browser).
moduleIdem al anterior, pero respecto a ES Modules en lugar de CommonJS.
scriptsColección de scripts del proyecto (lo veremos más adelante).
keywords de con palabras clave relacionadas con el proyecto. Util en búsquedas.
authorNombre del autor del paquete o un con name, email y/o url.
licenseTipo de licencia del paquete o proyecto. Por defecto, ISC.
dependenciesColección de paquetes para producción y la versión instalada.
devDependenciesColección de paquetes para desarrollo y la versión instalada.
homepageURL de la página principal del paquete.
repositoryURL del repositorio. Se debe indicar type (git, svn...) y url (ruta).
bugsObjeto con campo url con la URL de la página de issues del proyecto.

Si nuestro paquete (o alguna dependencia) tiene definidos estos últimos 3 campos en su package.json podemos utilizar los siguientes comandos, incluso si no tenemos instalada la dependencia en nuestro proyecto:

# Accede a la homepage de documentación del paquete "howler"
$ npm docs howler
$ npm home howler

# Accede al repositorio del paquete "howler"
$ npm repo howler

# Accede a la página de issues del paquete "howler"
$ npm issues howler
$ npm bugs howler

Dependencias del proyecto

En nuestro fichero package.json recién creado probablemente no existan los campos dependencies y devDependencies, pero si estamos ante un proyecto en el que ya han sido instalados paquetes, si existirán. El apartado dependencies contiene el nombre y versión de los paquetes de producción, mientras que el campo devDependencies contiene el nombre y versión de los paquetes de desarrollo:

# Mostramos los paquetes de producción del package.json
$ cat package.json | jq .dependencies
{
  "react": "^16.13.1",
  "howler": "^2.2.0"
}

Lo realmente interesante de estos campos es que funcionan a modo de índice o guía de paquetes necesarios para el proyecto, de modo que sólo con el fichero package.json en una carpeta vacía, podemos indicarle a npm que descargue todas las dependencias necesarias para el proyecto en la carpeta node_modules/ escribiendo lo siguiente:

# Pedimos a NPM que descargue las dependencias necesarias en node_modules/
$ npm install

Probablemente, este proceso tardará un rato, dependiendo del número de dependencias que sea necesario instalar, de su tamaño, de la conexión a Internet de la que dispongamos e incluso de si disponemos de un disco duro lento o un disco SSD rápido.

Una vez instalados los paquetes, tendremos nuestro proyecto listo para realizar bare imports, es decir, importaciones sin ruta (solo con el nombre del paquete), que node buscará en la carpeta node_modules/:

// Importamos la librería Howler de la carpeta node_modules/
import { Howler, Howl } from "howler";

const audio = new Howl({
  src: ["/assets/audio.mp3"]
});

Nota: Si quieres más información sobre las importaciones nativas de Javascript, echa un vistazo a las sentencias import y export en el artículo Módulos ECMAScript.

El archivo package-lock.json

El archivo package-lock.json es un archivo generado automáticamente cuando se instalan paquetes o dependencias en el proyecto. Su finalidad es mantener un historial de los paquetes instalados y optimizar la forma en que se generan las dependencias del proyecto y los contenidos de la carpeta node_modules/.

Este archivo debe conservarse e incluso versionarse para añadirlo al repositorio de control de versiones, puesto que es algo favorable para el trabajo con npm. Es por ello que no debe añadirse al fichero .gitignore.

¿Quién soy yo?

Soy Manz, vivo en Tenerife (España) y soy streamer partner en Twitch y profesor. Me apasiona el universo de la programación web, el diseño y desarrollo web y la tecnología en general. Aunque soy full-stack, mi pasión es el front-end, la terminal y crear cosas divertidas y locas.

Puedes encontrar más sobre mi en Manz.dev