Skip to main content
Version: 2.66.1

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. Install Required Dependencies​

Then, install the required dependencies for Watt:

npm install --save wattpm @platformatic/node

Where wattpm is the Watt CLI and @platformatic/node is the generic adapter for "bare" Node.js applications, if yours is a Next.js, Astro, or Remix application you might want to use the respective packages: @platformatic/next, @platformatic/remix, @platformatic/astro.

3. Create Configuration Files​

Create a watt.json in your project root:

{
  "$schema": "https://schemas.platformatic.dev/@platformatic/node/2.65.0.json",
  "node": {
    "main": "path/to/your/server/entry-point.js"
  },
  "runtime": {
    "server": {
      "hostname": "{HOSTNAME}",
      "port": "{PORT}"
    },
    "logger": {
      "level": "info"
    }
  }
}

Replace node.main with the path to your compiled server entry point (e.g., "dist/server.js" for TypeScript projects).

3. Update Environment Variables​

Add these variables to your .env file or .env.example:

# Watt
HOSTNAME=127.0.0.1
PORT=3000  # Choose your preferred port

You'll need to set HOSTNAME to 0.0.0.0 inside docker containers to allow external access.

4. Add an NPM Script​

Add a script to your package.json:

"scripts": {
  "watt-start": "wattpm start"
}

Starting Your Application​

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

npm run watt-start

Or directly with:

npx wattpm start

Common Issues and Solutions​

  • Port conflicts: If the specified port is already in use, Watt will try the next one.
  • Missing entry point: Verify that the path in watt-svc.json points to your actual server entry file.
  • Build step: For TypeScript projects, ensure you've built your project before running Watt. You can use npx wattpm build to compile your TypeScript files.
  • Environment variables: Confirm that all required environment variables are available.

Next-step: add more services​

In case you want to divide your application into multiple services, you can do so by creating multiple watt.json files, one for each service. Then you can add them to the watt.json file like this:

  "$schema": "https://schemas.platformatic.dev/@platformatic/runtime/2.65.0.json",
  "server": {
    "hostname": "{HOSTNAME}",
    "port": "{PORT}"
  },
  "logger": {
    "level": "info"
  },
  "services": [
    {
      "id": "service1",
      "config": "./service1/watt.json",
      "path": "./service1"
    },
    {
      "id": "service2",
      "config": "./service2/watt.json",
      "path": "./service2"
    }
  ]
}

In this case you are better served in using the autoload feature.

Each of the watt.json in the subfolders should look like this one:

{
  "$schema": "https://schemas.platformatic.dev/@platformatic/node/2.65.0.json",
  "node": {
    "main": "path/to/your/server/entry-point.js"
  }
}

Note that if you need to expose multiple services, you'd need to add a Composer.

Common Issues and Solutions​

  • Port conflicts: If the specified port is already in use, Watt will try the next one.
  • Missing entry point: Verify that the path in watt.json points to your actual server entry file.
  • Build step: For TypeScript projects, ensure you've built your project before running Watt. You can use npx wattpm build to compile your TypeScript files.
  • Environment variables: Confirm that all required environment variables are available.

Learn More​