Skip to main content
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.
Opción B: Automática (Por defecto) Genera el archivo inmediatamente aceptando todas las configuraciones predeterminadas.
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.
Sobre la inicialización en Square Cloud: Por defecto, Square Cloud ejecuta node MAIN (el archivo definido en MAIN), pero 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:
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:
2. Imports (Alias de rutas): Evita rutas relativas largas como ../../../utils. Con imports, creas atajos internos nativos (requiere una versión reciente de Node):
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: Mantenlo en Git: registra el árbol de dependencias exacto que funcionó en tu máquina. La CLI de Square Cloud y la extensión de VS Code dejan los archivos de bloqueo fuera de las subidas por defecto, así que Square Cloud instala las versiones más recientes que permiten los rangos de package.json. Cuando necesites las versiones fijadas, vuelve a incluirlo con !package-lock.json en tu squarecloud.ignore.
  • 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

​
Próximos pasos

Con tu archivo package.json configurado:
  1. Haz commit en tu repositorio Git.
  2. Aloja tu proyecto con la guía del runtime de Node.js, o sigue una guía de framework como Express o Next.js.
  3. Haz deploy automático desde GitHub en cada push.