# Watt Quick Start

Welcome to your first steps with Platformatic Watt, the Node.js Application Server.
This guide will help you set up and run an application composed of the following stack:

- [Next.js](https://nextjs.org/) frontend, to render our frontend
- Generic `node:http` [`createServer`](https://nodejs.org/docs/latest/api/http.html#httpcreateserveroptions-requestlistener),
  to showcase how to add an existing Node.js app
- [Platformatic Gateway](/docs/reference/gateway/overview), to coordinate/expose them all.

:::note
In this guide, we will use `Next.js` as our frontend framework, but Watt supports many more frameworks including Astro, Remix, Vite, and NestJS. See our [Framework Integration Guides](/docs/guides/frameworks) for complete details and setup instructions for all supported frameworks.
:::

:::tip
Prefer to let an AI coding agent set this up? Platformatic ships an official Agent Skill for Watt that works with Claude Code, Cursor, GitHub Copilot, and other agents. See [Use Watt with AI Coding Agents](/docs/guides/use-watt-with-ai-agents).
:::

## Prerequisites

Before starting, ensure you have the following installed:

- [Node.js](https://nodejs.org/) (v22.19.0+)
- [npm](https://docs.npmjs.com/cli/) (comes with Node.js)
- A code editor, (e.g., [Visual Studio Code](https://code.visualstudio.com/))

## Set up Watt

```bash
npx wattpm create
```

Which will output:

```
Hello YOURNAME, welcome to Watt!
? Where would you like to create your project? .
? Which package manager do you want to use? npm
? Which kind of application do you want to create? @platformatic/node
✔ Installing @platformatic/node using npm ...
? What is the name of the application? node
? Do you want to use TypeScript? no
? Do you want to create another application? no
? What port do you want to use? 3042
? Do you want to init the git repository? no
```

Dependencies are going to be installed. Your application is located in `web/node`.
The `watt.json` file is automatically created in the `node` folder, and the `package.json` file includes `@platformatic/node` as a dependency.

## Add your first Node.js application to Watt

By choosing the `@platformatic/node` application, you have already created your nodejs app.

This file is created as your nodejs app:

```js
import { getLogger } from '@platformatic/globals'
import { createServer } from 'node:http'

export function create () {
  const logger = getLogger()

  return createServer((_, res) => {
    logger.debug('Serving request.')
    res.writeHead(200, { 'content-type': 'application/json', connection: 'close' })
    res.end(JSON.stringify({ hello: 'world' }))
  })
}
```

The `getLogger()` function comes from [`@platformatic/globals`](../reference/runtime/globals.md), which exposes runtime APIs to applications running inside Watt.

:::note
In this example, we are using the built-in `node:http` module to
create a simple HTTP server that responds with a JSON object containing a counter.
You can see that we are returning a `create` function that creates the server.
This server will be run by Watt when the application starts in its
own worker thread.
:::

You can also use [Express](https://expressjs.com/), [Fastify](https://fastify.dev), [Koa](https://koajs.com/)
or any other Node.js framework.

### Start your Watt server

Run the following command in the root of project to start your Watt server:

```bash
npm start
```

This will internally run `wattpm start` and start your Watt server.

:::note

running `npm run start` at the root directory is running the watt server. if you run `npm run start` at the application directory(in this case `web/node`) it is running that single application via this command from the application package.json script: `start-platformatic-node`

:::

If you want to have a "watch mode" to automatically restart the server when you make changes, you can run this command in the root directory:

```bash
npm run dev
```

Which will run `wattpm dev` and start your Watt server in watch mode.

Your first Watt server is now live! 🌟 You can test it with:

```bash
curl http://localhost:3042
```

## Add a Platformatic Gateway to run multiple apps

Inside `node`, let's create a new Platformatic Gateway

```bash
npx wattpm create
```

This will output:

```
Hello YOURNAME, welcome to Watt!
Using existing configuration ...
? Which package manager do you want to use? npm
? Which kind of application do you want to create? @platformatic/gateway
✔ Installing @platformatic/gateway using npm ...
? What is the name of the application? gateway
? Do you want to use TypeScript? no
? Do you want to create another application? no
? Which application should be exposed? gateway
```

Start your Watt server again:

You can run these commands in the root directory:

```bash
npm start
```

If you want to have a "watch mode" to automatically restart the server when you make changes, you can run this command in the root directory:

```bash
npm run dev
```

Which will run `wattpm dev` and start your Watt server in watch mode.

Then, you can test it with:

```bash
curl http://localhost:3042/node
```

:::note

You can customize how the various applications are exposed by changing `web/gateway/watt.json`.
Here is the equivalent of the default configuration when exposing a Node.js application:

```json
{
  "$schema": "https://schemas.platformatic.dev/@platformatic/gateway/3.0.0.json",
  "gateway": {
    "applications": [
      {
        "id": "node",
        "proxy": {
          "prefix": "/node"
        }
      }
    ],
    "refreshTimeout": 1000
  },
  "watch": true
}
```

:::

## Add a Next.js application to Watt

Inside `node`, let's create a new Next.js app:

```bash
npx create-next-app web/next
```

Which will output:

```
✔ Would you like to use TypeScript? … No
✔ Which linter would you like to use? › ESLint
✔ Would you like to use React Compiler? No
✔ Would you like to use Tailwind CSS? … No
✔ Would you like your code inside a `src/` directory? … Yes
✔ Would you like to use App Router? (recommended) … Yes
✔ Would you like to customize the import alias (`@/*` by default)? … No
```

:::caution[Two adjustments are needed for npm workspaces]

A Watt project declares `"workspaces": ["web/*"]`, and that hoists dependencies to the project root.
Two things need adjusting before the Next.js application will start.

**1. Rename the workspace package.** `create-next-app web/next` names the generated package after its
directory, so `web/next/package.json` gets `"name": "next"`. npm then links `node_modules/next` to
`web/next`, and that symlink **shadows the Next.js framework itself** — resolving `next` from the
project root returns your application instead of Next.js. The dev server fails with a cascade of
`Module not found: Can't resolve 'react'` and `Can't resolve '@swc/helpers/...'` errors.

Open `web/next/package.json` and change the `name` field to something that is not a package you depend
on:

```json
{
  "name": "frontend"
}
```

The directory can stay `web/next` — Watt derives the application id from the directory, so the `/next`
prefix used below is unaffected. Only the package `name` needs to change.

**2. Set `turbopack.root`.** Next.js 16 builds with Turbopack by default. Turbopack infers a workspace
root, and because npm hoisted `next` to the Watt project root it cannot resolve `next/package.json`
from the application directory. It fails with:

```
Next.js inferred your workspace root, but it may not be correct.
We couldn't find the Next.js package (next/package.json) from the project directory
```

Inside Watt this surfaces as the worker exiting during startup:

```
Failed to start worker 0 of the application "next": The worker 0 of the
application "next" exited prematurely with error code 1
```

Point Turbopack at the Watt project root in `web/next/next.config.mjs`:

```js
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'

/** @type {import('next').NextConfig} */
const nextConfig = {
  turbopack: {
    // The Watt project root, where npm workspaces hoists the `next` package.
    root: resolve(dirname(fileURLToPath(import.meta.url)), '../..')
  }
}

export default nextConfig
```

Both issues are npm workspace resolution problems rather than Watt runtime bugs — the Turbopack one
reproduces with plain `next dev`, outside Watt entirely.

:::

Then, let's import it to our Watt server:

```bash
npx wattpm-utils import
```

This will also install the required dependencies. The command will output:

```
[13:06:10.996] INFO (42432): Application next is using Next.js. Adding @platformatic/next to its package.json dependencies.
[13:06:10.998] INFO (42432): Installing dependencies for the project using npm ...
[13:06:12.119] INFO (42432): Installing dependencies for the application gateway using npm ...
[13:06:13.092] INFO (42432): Installing dependencies for the application node using npm ...
[13:06:14.310] INFO (42432): Installing dependencies for the application next using npm ...
```

Then, we need to tell Watt to expose our `next` server on `/next` by modifying `web/next/watt.json`:

```json
{
  "$schema": "https://schemas.platformatic.dev/@platformatic/next/3.0.0.json",
  "application": {
    "basePath": "/next"
  }
}
```

You can run `npm run dev` to start your Watt server in dev/watch mode, which in turn will start Next.js
in development mode.

Then, you can test it by opening your browser at [`http://localhost:3042/next`](http://localhost:3042/next).

:::note

In this example, we are exposing the Next.js app at `/next` and the Node.js app at `/node`.
You can change the paths to suit your needs. Make sure to alter the `basePath` in `web/next/watt.json`
and the `prefix` in `web/gateway/watt.json` accordingly if you customize it.

:::

## `fetch` the data from the Node.js app in the Next.js app

Replace `web/next/src/app/page.js` with the following code:

```js
import styles from './page.module.css'

export default async function Home () {
  const { hello } = await (await fetch('http://node.plt.local', { cache: 'no-store' })).json()
  return (
    <div className={styles.page}>
      <main className={styles.main}>Hello {hello}</main>
    </div>
  )
}
```

This will fetch the data from the Node.js app and display it in the Next.js app.
Note that it uses the `node.plt.local` hostname, which is the _internal_ hostname for the `node` application.
This domain name would not work outside of a Watt or Platformatic environment.

:::note

By default Next.js caches all `fetch()` requests.
The `{ cache: 'no-store' }` option is used to disable caching, so that you can see the counter incrementing.

:::

Launch it with: `npm run dev`.

You can now test it by opening your browser at [`http://localhost:3042/next`](http://localhost:3042/next).

## Build and Production mode

To create a build for production, you can run `wattpm build`, which is exposed as npm script:

```bash
npm run build
```

Which will in turn create a build for Next.js and for the Node.js app (in case that is needed).

To run the server in production mode, you can run:

```bash
npm run start
```

which will call `wattpm start`.

## Debug individual applications with Chrome DevTools

You can debug your Watt server with Chrome DevTools by running:

```bash
npm run start -- --inspect
```

This will start an inspector instance in each application, and you can connect to it with Chrome DevTools.
Open `chrome://inspect` in Chrome, and you will see the applications listed there.

![Chrome Inspector showing 4 applications](./images/inspector.png)

Then, you can click on `inspect` to open the DevTools for that application.

## Debug individual applications with VS Code

You can debug the code of individual Watt applications directly in VS Code.

To run the debugger in VS Code:

- add a breakpoint in your Watt application code
- open the `Command Palette` (`Ctrl+Shift+P` on Windows, `CMD+Shift+P` on Mac)
- search `Debug: Toggle Auto Attach`, then select `Always` from the list of options
- run watt with `npm run dev`
- you should now see in your shell a log that confirms that the debugger is listening

```shell
Debugger listening on ws://127.0.0.1:62807/6132054c-766e-4d86-a716-f634118275ed
For help, see: https://nodejs.org/en/docs/inspector
Debugger attached.
```

- do a request to your application, to trigger the breakpoint code, and use VS Code to debug it as by the following screenshot

![VS Code Debug Watt application](./images/vs-code-debug.png)
