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

# How to create your package.json file

> Complete guide to the package.json file in Node.js: learn how to create, configure scripts, manage dependencies, and prepare your project for production deployment.

# 📋 package.json file for Node.js

The `package.json` file is the heart of any Node.js project. It acts as a manifest that lists dependencies, defines automation scripts, and configures the project's behavior.

This guide teaches how to configure a robust `package.json`, ensuring your project is reproducible, organized, and compatible with the Square Cloud environment.

***

<Steps>
  <Step title="Initialize the project">
    The safest way to create the file is by using the NPM CLI. Navigate to the root of your project and choose one of the options:

    **Option A: Interactive (Recommended for beginners)**
    Answer the questions step-by-step to configure custom metadata.

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

    **Option B: Automatic (Default)**
    Generates the file immediately accepting all default settings.

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

  <Step title="Configure essential metadata">
    Open the generated `package.json`. For a professional project, ensure these fields are filled correctly:

    * `name`: Unique project identifier (use kebab-case, e.g., `my-project-api`).
    * `version`: Follows the SemVer standard (e.g., `1.0.0`).
    * `main`: The entry point of the application (usually `index.js` or `src/index.js`).
    * `type`: Set as `"module"` if using ES Modules (import/export) or remove to use CommonJS (require).
  </Step>

  <Step title="Configure execution scripts">
    The `scripts` section is vital for automation. This is where you define how your application should be started, tested, or built.

    ```json theme={null}
    "scripts": {
      "start": "node index.js",
      "test": "echo \"Error: no test specified\" && exit 1"
    }
    ```

    **About initialization on Square Cloud:**
    Although the environment looks for common patterns, Square Cloud offers full flexibility. You can (and should) explicitly configure which command the system should execute to start your application.

    For example, you can configure the **Start Command** in the dashboard or in the Square configuration file to execute `npm run start`, ensuring that the script defined above is respected.
  </Step>

  <Step title="Manage dependencies">
    Here lie the essential libraries for your code to run in production. To install and automatically save to this list:

    ```bash theme={null}
    npm install package-name
    ```

    **Attention to `devDependencies` and Build on Square Cloud:**
    Tools used only in local development (like `eslint` or `prettier`) stay in `devDependencies`.

    <Warning>
      **Important:** Square Cloud performs installation in production mode by default, which means packages listed in `devDependencies` are **NOT** installed.

      If you need to run a **build** process in the cloud (e.g., compile TypeScript or run post-install scripts), you must move those tools to `dependencies`. Otherwise, the build will fail due to missing packages.
    </Warning>
  </Step>

  <Step title="Use advanced features">
    For more complex projects, `package.json` offers powerful control features:

    **1. Overrides (Force versions):**
    Useful when a dependency you use installs a sub-dependency with multiple vulnerabilities. You can force resolution to a safe version:

    ```json theme={null}
    "overrides": {
      "vulnerable-package": "2.0.1"
    }
    ```

    **2. Imports (Path aliases):**
    Avoid long relative paths like `../../../utils`. With `imports`, you create native internal shortcuts (requires recent Node):

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

    This allows importing in code using `import db from '#database'`.
  </Step>
</Steps>

***

## 💡 Tips and Best Practices

* **Semantic Versioning**: Prefer fixing critical versions by removing `^` (e.g., use `"14.14.1"` instead of `"^14.14.1"`) to prevent automatic updates from breaking your production code.
* **Security**: Run `npm audit` regularly to identify vulnerabilities in your dependencies. The `overrides` field taught above is the ideal solution to fix these issues.
* **Package-lock.json**: Never delete or ignore this file in `.gitignore`. It is the guarantee that Square Cloud will install the exact dependency tree that worked on your machine.
* **Organization**: Keep the file clean. If the `scripts` section gets too big, consider using external automation tools or separating into files.

***

## 📄 Final File Example

Below, an example of a modern and optimized `package.json`:

```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"
  }
}
```

***

## 🚀 Next Steps

With your `package.json` file configured:

1. Commit to your Git repository.
2. Host your project on **Square Cloud**.
3. Configure automatic deploy via GitHub.
4. Welcome to professional Node.js application hosting!

A well-structured `package.json` file is the foundation for any successful Node.js application, ensuring your application works perfectly on Square Cloud.