Skip to main content
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.
Option B: Automatic (Default) Generates the file immediately accepting all default settings.
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.
About initialization on Square Cloud: By default, Square Cloud runs node MAIN (the file set in MAIN), but it 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:
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:
2. Imports (Path aliases): Avoid long relative paths like ../../../utils. With imports, you create native internal shortcuts (requires recent Node):
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: Keep it in Git: it records the exact dependency tree that worked on your machine. The Square Cloud CLI and the VS Code extension leave lockfiles out of uploads by default, so Square Cloud installs the newest versions allowed by the ranges in package.json. When you need the pinned versions, re-include it with !package-lock.json in your squarecloud.ignore.
  • 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

​
Next steps

With your package.json file configured:
  1. Commit it to your Git repository.
  2. Host your project with the Node.js runtime guide, or follow a framework guide such as Express or Next.js.
  3. Deploy automatically from GitHub on every push.