package.json

Fundamentos

Los dos campos más importantes de su package.json son name y version, sin ellos su paquete no podrá ser instalado. Los campos name y version son usados en conjunto para crear un identificador único.

name

{
  "name": "my-awesome-package"
}

Este es el nombre del paquete. Es utilizado en URLs, como un argumento en la línea de comandos, y como el nombre del directorio dentro de la carpeta node_modules.

yarn add [name]
node_modules/[name]


https://registry.npmjs.org/[name]/-/[name]-[version].tgz

Reglas

  • Debe tener menos o exactamente 214 caracteres (incluyendo el @scope/ para scoped packages).
  • No debe comenzar ni con punto (.) ni guión bajo (_).
  • No debe incluir ninguna letra mayúscula en el nombre.
  • Debe usar caracteres permitidos en URL.

Trucos

  • No use nombres de módulos del core de Node.js
  • No incluya en el nombre ni js ni node.
  • Use nombres cortos y descriptivos. Querrá que la gente entienda de donde proviene el nombre, pero también será usado en llamadas require().
  • Asegúrese de no haber ya otro con el mismo nombre en el registry.

version

{
  "version": "1.0.0"
}

La versión actual de su paquete.

Información

description

{
  "description": "My short description of my awesome package"
}

La descripción es solo un string que ayuda a entender el propósito del paquete. Puede ser usado en las búsquedas de paquetes en los administradores de paquetes.

keywords

{
  "keywords": ["short", "relevant", "keywords", "for", "searching"]
}

Keywords son una array de strings ùtiles al realizar búsquedas de paquetes en un administrador de paquetes.

license

{
  "license": "MIT",
  "license": "(MIT or GPL-3.0)",
  "license": "SEE LICENSE IN LICENSE_FILENAME.txt",
  "license": "UNLICENSED"
}

Todos los paquetes deben especificar una licencia para que los usuarios sepan cómo se les permite utilizarlo y cualquier restricción que estés poniendo en él.

Es recomendable que use una licencia Open Source (OSI-approved) a no ser que tenga una razòn específica para no hacerlo. Si crea su paquete como parte de su trabajo es bueno verificarlo en su empresa antes de optar por una licencia.

Debe ser alguna de las siguientes:

  • Un identificador de licencia SPDX vàlido si està usando una licencia estàndar.
  • Una licencia SPDX expression syntax 2.0 válida si estás usando múltiples licencias estándar.
  • Una cadena de texto que diga SEE LICENSE IN <nombre_de_archivo> y que apunte a <nombre_de_archivo> en el directorio de nivel superior de tu paquete si estás usando una licencia no-estándar.
  • Una cadena de texto que diga UNLICENSED si no deseas dar permiso a otros de usar un paquete privado o no publicado bajo ningún término.

Enlaces

Varios enlaces a la documentacion, lugares para reportar incidentes y al lugar en donde el código de tu paquete vive.

homepage

{
  "homepage": "https://your-package.org"
}

El homepage es la url para la documentación o página de presentación de tu paquete.

bugs

{
  "bugs": "https://github.com/user/repo/issues"
}

Es la página para el seguimiento de incidencias de tu proyecto. Esto también puede ser una dirección de correo electrónico. Provee a los usuarios una manera de reportar incidencias con tu paquete.

repository

{
  "repository": { "type": "git", "url": "https://github.com/user/repo.git" },
  "repository": "github:user/repo",
  "repository": "gitlab:user/repo",
  "repository": "bitbucket:user/repo",
  "repository": "gist:a1b2c3d4e5f"
}

El repositorio es el lugar donde el código de tu paquete vive.

Mantenedores

Los mantenedores/responsables de tu proyecto

author

{
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "url": "http://your-website.com"
  },
  "author": "Your Name <you@example.com> (http://your-website.com)"
}

Información del autor del paquete. Un autor es una persona.

contributors

{
  "contributors": [
    { "name": "Your Friend", "email": "friend@example.com", "url": "http://friends-website.com" }
    { "name": "Other Friend", "email": "other@example.com", "url": "http://other-website.com" }
  ],
  "contributors": [
    "Your Friend <friend@example.com> (http://friends-website.com)",
    "Other Friend <other@example.com> (http://other-website.com)"
  ]
}

Los colaboradores de tu paquete. Los colaboradores son un arreglo de personas.

Archivos

Puedes especificar los archivos que serán incluidos en tu proyecto, junto con el archivo principal de tu proyecto.

files

{
  "files": ["filename.js", "directory/", "glob/*.{js,json}"]
}

Estos son archivos que están incluidos en tu proyecto. Puedes especificar archivos individuales, directorios enteros o utilizar comodines para incluir archivos que cumplan ciertos criterios.

main

{
  "main": "filename.js"
}

Este es el punto de entrada principal para la funcionalidad de tu proyecto.

bin

{
  "bin": "bin.js",
  "bin": {
    "command-name": "bin/command-name.js",
    "other-command": "bin/other-command"
  }
}

Archivos ejecutables incluidos en tu proyecto que serán instalados.

man

{
  "man": "./man/doc.1",
  "man": ["./man/doc.1", "./man/doc.2"]
}

Si tienes páginas man asociadas a tu proyecto, agrégalas aquí.

directories

{
  "directories": {
    "lib": "path/to/lib/",
    "bin": "path/to/bin/",
    "man": "path/to/man/",
    "doc": "path/to/doc/",
    "example": "path/to/example/"
  }
}

Al instalar tu paquete, puedes especificar ubicaciones exactas para poner archivos binarios, páginas de manual, documentación, ejemplos, etcétera.

Tasks

Tu paquete puede incluir secuencias de comandos ejecutables u otra configuración.

scripts

{
  "scripts": {
    "build-project": "node build-project.js"
  }
}

Los scripts son una gran manera de automatizar las tareas relacionadas con tu paquete, como simples procesos de compilación o herramientas de desarrollo. Utilizando el campo "scripts", puedes definir varios scripts que se ejecutarán como yarn run <script>. Por ejemplo, el script build-project de arriba puede ser invocado con yarn run build-project y ejecutará node build-project.js.

Ciertos nombres de script son especiales. Si está definido, el script preinstall es llamado por Yarn antes de que tu paquete sea instalado. Por razones de compatibilidad, scripts llamados install, postinstall y prepublish se llamarán después de que tu paquete haya finalizado su instalación.

El valor del script start está predeterminado a node server.js.

config

{
  "config": {
    "port": "8080"
  }
}

Opciones de configuración o parámetros utilizados en los scripts.

Dependencias

Tu paquete muy probablemente dependerá de otros paquetes. Puedes especificar estas dependencias en el archivo package.json.

dependencies

{
  "dependencies": {
    "package-1": "^3.1.4"
  }
}

Estas son las dependencias que se requieren en desarrollo y producción de tu paquete.

Puedes especificar una versión exacta, una versión mínima (Por ejemplo: >=) o un rango de versiones (Por ejemplo: >= ... <).

devDependencies

{
  "devDependencies": {
    "package-2": "^0.4.2"
  }
}

Estos son paquetes que sólo se requieren en el desarrollo de tu paquete pero no se instalará en producción.

peerDependencies

{
  "peerDependencies": {
    "package-3": "^2.7.18"
  }
}

Las dependencias pares permiten establecer compatibilidad de tu paquete con versiones de otros paquetes.

optionalDependencies

{
  "optionalDependencies": {
    "package-5": "^1.6.1"
  }
}

Las dependencias opcionales pueden ser usadas con tu paquete pero no son requeridas. Si el paquete opcional no se encuentra, la instalación continúa.

bundledDependencies

{
  "bundledDependencies": ["package-4"]
}

Las dependencias empaquetadas son un arreglo de nombres de paquetes que será empaquetadas al publicar tu paquete.

flat

{
  "flat": true
}

Si tu paquete solo permite una versión de una determinada dependencia, y deseas forzar el mismo comportamiento de yarn install --flat en la línea de comandos, debes establecer esta opción a true.

Ten en cuenta que si tu archivo package.json contiene "flat": true y otros paquetes dependen del tuyo (Por ejemplo: estás construyendo una librería en lugar de una aplicación), los otros paquetes también necesitarán "flat": true en su archivo package.json o ser instalados con yarn install --flat en la línea de comandos.

resolutions

{
  "resolutions": {
    "transitive-package-1": "0.0.29",
    "transitive-package-2": "file:./local-forks/transitive-package-2",
    "dependencies-package-1/transitive-package-3": "^2.1.1"
  }
}

Allows you to override a version of a particular nested dependency. See the Selective Versions Resolutions RFC for the full spec.

Note that installing dependencies via [yarn install --flat] will automatically add a resolutions block to your package.json file.

Sistema

Puedes proveer información a nivel de sistema asociada con el paquete, tales como compatibilidad de sistema operativo, etc.

engines

{
  "engines": {
    "node": ">=4.4.7 <7.0.0",
    "zlib": "^1.2.8",
    "yarn": "^0.14.0"
  }
}

La opción engines especifica versiones de clientes que deben ser usadas con tu paquete. Esto comprueba contra process.versions así como la versión actual de Yarn.

Esto verifica que siga las reglas semver con una excepción. It allows prerelease versions to match semvers that do not explicitly specify a prerelease. For example, 1.4.0-rc.0 matches >=1.3.0, while it would not match a typical semver check.

os

{
  "os": ["darwin", "linux"],
  "os": ["!win32"]
}

Esto especifica la compatibilidad de sistema operativo de tu paquete. Esto comprueba contra process.platform.

cpu

{
  "cpu": ["x64", "ia32"],
  "cpu": ["!arm", "!mips"]
}

Utiliza esto para especificar que tu paquete solo se ejecutará en ciertas arquitecturas de CPU. Esto comprueba contra process.arch.

Publicación

private

{
  "private": true
}

Si no deseas que tu paquete sea publicado en un manejador de paquetes, establece esto a true.

publishConfig

{
  "publishConfig": {
    ...
  }
}

Estos valores de configuración serán usados cuando tu paquete sea publicado. Puedes etiquetar tu paquete, por ejemplo.