JavaScript
Paquetes, dependencias y package.json
Explica el papel de package.json, las dependencias de producción y desarrollo, el versionado semántico y los campos que definen un paquete JavaScript.
- Última actualización
- Actualizada
- Nivel
- Aplicación
JavaScript
Explica el papel de package.json, las dependencias de producción y desarrollo, el versionado semántico y los campos que definen un paquete JavaScript.
Un paquete agrupa código, metadatos y una interfaz de distribución. En el ecosistema Node.js se describe normalmente mediante package.json.
{
"name": "@example/prices",
"version": "1.0.0",
"type": "module",
"exports": {
".": "./dist/index.js"
}
}Es una convención y contrato del ecosistema. Campos concretos son interpretados por Node.js, package managers, registries y herramientas.
{
"dependencies": {
"zod": "^4.0.0"
},
"devDependencies": {
"vitest": "^4.0.0"
}
}dependencies: necesarias para ejecutar o consumir el paquete.devDependencies: necesarias para desarrollo, pruebas o build.peerDependencies: el consumidor debe proporcionar una versión compatible.optionalDependencies: su instalación o disponibilidad puede fallar sin invalidar necesariamente el paquete.La interpretación exacta depende del package manager y del tipo de paquete.
major.minor.patchLos rangos como ^ y ~ expresan qué actualizaciones acepta el resolvedor. Un lockfile registra versiones concretas para instalaciones reproducibles.
{
"type": "module"
}En Node.js determina cómo se interpretan archivos .js dentro del scope del paquete. .mjs sigue siendo ESM y .cjs CommonJS.
main es una entrada histórica.
{
"main": "./dist/index.cjs"
}exports define una superficie más controlada.
{
"exports": {
".": "./dist/index.js",
"./testing": "./dist/testing.js"
}
}Cuando exports está presente, rutas internas no declaradas pueden dejar de ser importables.
import {
createClient,
} from "@example/sdk";Un consumidor no debería depender de:
import helper from "@example/sdk/src/internal/helper.js";La ruta interna puede cambiar sin ser parte del contrato. exports ayuda a imponer ese límite.
{
"exports": {
".": {
"browser": "./dist/browser.js",
"node": "./dist/node.js",
"default": "./dist/index.js"
}
}
}El orden y condiciones reconocidas dependen del runtime y herramientas. Mantén alternativas equivalentes en API.
{
"imports": {
"#logger": "./src/logger.js"
}
}Permite aliases internos controlados por el paquete en Node.js.
{
"scripts": {
"test": "vitest run",
"build": "tsc -p tsconfig.build.json"
}
}Son comandos del package manager, no funciones importables.
Registra el grafo resuelto. Debe mantenerse según la política del proyecto para:
No sustituye auditar dependencias ni definir rangos correctos.
Tu proyecto puede ejecutar código que no declaraste directamente porque una dependencia lo instaló.
Evalúa:
Herramientas pueden eliminar exports no utilizados cuando el grafo y los efectos son analizables.
Un paquete con efectos globales puede impedir optimizaciones.
{
"sideEffects": false
}Este campo es una promesa a bundlers. Marcarlo incorrectamente puede eliminar código necesario.
{
"name": "@example/core",
"type": "module",
"exports": {
".": "./dist/index.js",
"./errors": "./dist/errors.js"
}
}import { createOrder } from "@example/core";
import { OrderError } from "@example/core/errors";La superficie pública es pequeña y explícita.
.js en Node.¿Qué riesgo existe al importar package/src/internal.js?
Dependes de una ruta que probablemente no forma parte de la API pública y puede cambiar sin considerarse breaking change.
Bundling, transpilation y source maps explica cómo las herramientas transforman y entregan módulos.