Skip to main content

​
📋 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.
1

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.
npm init
Option B: Automatic (Default) Generates the file immediately accepting all default settings.
npm init -y
2

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).
3

Configure execution scripts

The scripts section is vital for automation. This is where you define how your application should be started, tested, or built.
"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.
4

Manage dependencies

Here lie the essential libraries for your code to run in production. To install and automatically save to this list:
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.
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.
5

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:
"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):
"imports": {
  "#utils/*": "./src/utils/*.js",
  "#database": "./src/core/database.js"
}
This allows importing in code using import db from '#database'.

​
💡 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:
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"
  }
}

​
🚀 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.