Skip to main content
Version: Next

Running Your Project in Watt

This guide explains how to set up any Node.js project to run in Watt, the Node.js Application Server.

Why Use Watt?

Watt is a powerful environment manager for your Node.js applications that provides:

  • Simplified deployment
  • Built-in support for multiple services
  • Multi-threading
  • Standardized environment configuration
  • Service orchestration
  • Gateway capabilities
  • Standardized logging
  • Standardized monitoring
  • ...and much more!

Setup Instructions

Follow these steps to make your project run in Watt:

0. Prerequisites

Before we begin, make sure you have the following installed:

  • Node.js (v20.16.0+ or v22.3.0+)
  • A Node.js application to run. These steps have been tested on the official Fastify demo.

1. Clone your Project

If you haven't already, clone your project repository. For example, to clone the Fastify demo:

git clone [email protected]:fastify/demo.git

Then, navigate to the project directory and install its dependencies:

cd demo
npm install

2. Use wattpm create

Use wattpm create to wrap your application inside Watt.

$ pnpx wattpm create
Hello User, welcome to Watt 2.66.1!
? This folder seems to already contain a Node.js application. Do you want to wrap into Watt? yes
? What port do you want to use? 3042
[15:59:20.315] INFO (53128): /home/user/work/demo/.env written!
[15:59:20.319] INFO (53128): /home/user/work/demo/.env.sample written!
[15:59:20.319] INFO (53128): /home/user/work/demo/package.json written!
[15:59:20.320] INFO (53128): /home/user/work/demo/watt.json written!
[15:59:20.320] INFO (53128): Installing dependencies for the application using pnpm ...
[15:59:37.237] INFO (53128): You are all set! Run `pnpm start` to start your project.

3. Setup application commands (optional)

If your application is using custom commands to start, you must set them in your watt.json. Modify the application.commands property like in the example below:

{
"$schema": "https://schemas.platformatic.dev/@platformatic/node/2.67.0.json",
"application": {
"commands": {
"development": "npm run dev",
"build": "npm run build",
"start": "npm run start"
}
},
"runtime": {
"logger": {
"level": "{PLT_SERVER_LOGGER_LEVEL}"
},
"server": {
"hostname": "{PLT_SERVER_HOSTNAME}",
"port": "{PORT}"
},
"managementApi": "{PLT_MANAGEMENT_API}"
}
}

Starting Your Application

Once everything is set up, you can start your application in development mode with:

wattpm dev

or, you can build and start your application in production mode:

wattpm build
wattpm start

Common Issues and Solutions

  • Port conflicts: If the specified port is already in use, Watt will try the next one.
  • Missing scripts: If you use a custom start script, insert into the watt.json file in the section application.commands.start. See the step 3 above for more informations.
  • Build step: For TypeScript projects, ensure you've built your project before running Watt. You can use wattpm build to compile your TypeScript files.
  • Environment variables: Confirm that all required environment variables are available.

Learn More