> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Cómo crear tu archivo package.json

> Guía completa del archivo package.json en Node.js: aprende a crearlo, configurar scripts, gestionar dependencias y preparar tu proyecto para el despliegue en producción.

# 📋 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.

***

<Steps>
  <Step title="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.

    ```bash theme={null}
    npm init
    ```

    **Opción B: Automática (Por defecto)**
    Genera el archivo inmediatamente aceptando todas las configuraciones predeterminadas.

    ```bash theme={null}
    npm init -y
    ```
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.

    ```json theme={null}
    "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.
  </Step>

  <Step title="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:

    ```bash theme={null}
    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`.

    <Warning>
      **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.
    </Warning>
  </Step>

  <Step title="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:

    ```json theme={null}
    "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):

    ```json theme={null}
    "imports": {
      "#utils/*": "./src/utils/*.js",
      "#database": "./src/core/database.js"
    }
    ```

    Esto permite importar en el código usando `import db from '#database'`.
  </Step>
</Steps>

***

## 💡 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:

```json package.json theme={null}
{
  "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.