Saltar al contenido principal

​
📋 Archivo package.json para Node.js

El archivo package.json es el corazón de cualquier proyecto Node.js. Actúa como un manifiesto que lista las dependencias, define scripts de automatización y configura el comportamiento del proyecto. Esta guía enseña cómo configurar un package.json robusto, asegurando que tu proyecto sea reproducible, organizado y compatible con el entorno de Square Cloud.
1

Inicializa el proyecto

La forma más segura de crear el archivo es usando la CLI de NPM. Navega a la raíz de tu proyecto y elige una de las opciones:Opción A: Interactiva (Recomendada para principiantes) Responde las preguntas paso a paso para configurar metadatos personalizados.
npm init
Opción B: Automática (Por defecto) Genera el archivo inmediatamente aceptando todas las configuraciones predeterminadas.
npm init -y
2

Configura los metadatos esenciales

Abre el package.json generado. Para un proyecto profesional, asegúrate de que estos campos estén rellenados correctamente:
  • name: Identificador único del proyecto (usa kebab-case, por ejemplo, my-project-api).
  • version: Sigue el estándar SemVer (por ejemplo, 1.0.0).
  • main: El punto de entrada de la aplicación (normalmente index.js o src/index.js).
  • type: Establécelo como "module" si usas ES Modules (import/export) o elimínalo para usar CommonJS (require).
3

Configura los scripts de ejecución

La sección scripts es vital para la automatización. Aquí es donde defines cómo se debe iniciar, probar o compilar tu aplicación.
"scripts": {
  "start": "node index.js",
  "test": "echo \"Error: no test specified\" && exit 1"
}
Sobre la inicialización en Square Cloud: Aunque el entorno busca patrones comunes, Square Cloud ofrece total flexibilidad. Puedes (y deberías) configurar explícitamente qué comando debe ejecutar el sistema para iniciar tu aplicación.Por ejemplo, puedes configurar el Start Command en el dashboard o en el archivo de configuración de Square para ejecutar npm run start, asegurando que se respete el script definido anteriormente.
4

Gestiona las dependencias

Aquí residen las librerías esenciales para que tu código se ejecute en producción. Para instalar y guardar automáticamente en esta lista:
npm install package-name
Atención a devDependencies y al Build en Square Cloud: Las herramientas usadas únicamente en el desarrollo local (como eslint o prettier) permanecen en devDependencies.
Importante: Square Cloud realiza la instalación en modo producción por defecto, lo que significa que los paquetes listados en devDependencies NO se instalan.Si necesitas ejecutar un proceso de build en la nube (por ejemplo, compilar TypeScript o ejecutar scripts post-install), debes mover esas herramientas a dependencies. De lo contrario, el build fallará por falta de paquetes.
5

Usa funciones avanzadas

Para proyectos más complejos, package.json ofrece potentes funciones de control:1. Overrides (Forzar versiones): Útil cuando una dependencia que usas instala una sub-dependencia con múltiples vulnerabilidades. Puedes forzar la resolución a una versión segura:
"overrides": {
  "vulnerable-package": "2.0.1"
}
2. Imports (Alias de rutas): Evita rutas relativas largas como ../../../utils. Con imports, creas atajos internos nativos (requiere una versión reciente de Node):
"imports": {
  "#utils/*": "./src/utils/*.js",
  "#database": "./src/core/database.js"
}
Esto permite importar en el código usando import db from '#database'.

​
💡 Consejos y buenas prácticas

  • Versionado semántico: Prefiere fijar versiones críticas eliminando ^ (por ejemplo, usa "14.14.1" en lugar de "^14.14.1") para evitar que las actualizaciones automáticas rompan tu código en producción.
  • Seguridad: Ejecuta npm audit regularmente para identificar vulnerabilidades en tus dependencias. El campo overrides enseñado anteriormente es la solución ideal para corregir estos problemas.
  • Package-lock.json: Nunca elimines ni ignores este archivo en .gitignore. Es la garantía de que Square Cloud instalará el árbol de dependencias exacto que funcionó en tu máquina.
  • Organización: Mantén el archivo limpio. Si la sección scripts se vuelve demasiado grande, considera usar herramientas de automatización externas o separar en archivos.

​
📄 Ejemplo de archivo final

A continuación, un ejemplo de un package.json moderno y optimizado:
package.json
{
  "name": "square-cloud-project",
  "version": "1.0.0",
  "description": "Professional Node.js API",
  "main": "src/index.js",
  "type": "module",
  "scripts": {
    "start": "node src/index.js",
    "lint": "eslint ."
  },
  "imports": {
    "#services/*": "./src/services/*.js"
  },
  "dependencies": {
    "discord.js": "14.14.1",
    "dotenv": "16.3.1",
    "typescript": "5.3.3" 
  },
  "devDependencies": {
    "eslint": "8.56.0"
  }
}

​
🚀 Próximos pasos

Con tu archivo package.json configurado:
  1. Haz commit a tu repositorio Git.
  2. Aloja tu proyecto en Square Cloud.
  3. Configura el deploy automático a través de GitHub.
  4. ¡Bienvenido al alojamiento profesional de aplicaciones Node.js!
Un archivo package.json bien estructurado es la base de cualquier aplicación Node.js exitosa, asegurando que tu aplicación funcione perfectamente en Square Cloud.