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 applications
  • Multi-threading
  • Standardized environment configuration
  • Application 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 (v22.19.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 npm create wattpm​

Use npm create wattpm to wrap your application inside Watt.

$ npm create wattpm
Hello YOURNAME, welcome to Watt 3.0.0!
? 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 npm ...
[15:59:37.237] INFO (53128): You are all set! Run `npm 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/3.0.0.json",
  "application": {
    "commands": {
      "development": "npm run dev",
      "build": "npm run build",
      "production": "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

Port your Next.js application to Watt​

In order to run your existing Next.js application with Watt, you can use the import capability of wattpm-utils.

From the root of your application, run:

npx wattpm-utils import

The command will create a watt.json for you and also install @platformatic/next as part of your dependencies.

By default, Watt will run on random port. If you want to choose a specific port, add an entry in the watt.json file:

{
  "$schema": "https://schemas.platformatic.dev/@platformatic/next/3.8.0.json?autogenerated=true",
  "runtime": {
    "server": {
      "port": 3000
    }
  }
}

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