Watt, The Node.js Application Server

Common errors

• Error: Cannot find module '@platformatic/service'

  cause One of Watt's core dependencies, such as @platformatic/service or @platformatic/runtime, is missing or incorrectly installed.
  fix Run `npm install` or `pnpm install` in your project root to ensure all `@platformatic/*` dependencies are correctly installed. Verify your `package.json` for `wattpm` and its peer dependencies.

• Error: `server.hostname` option must be a string

  cause The `server.hostname` in your Platformatic configuration is either missing or set to an invalid type, especially after the fix in v3.52.0 where implicit defaults were changed.
  fix Explicitly set `server.hostname` to a valid string (e.g., `'127.0.0.1'` or `'0.0.0.0'`) in your `platformatic.json` or `platformatic.service.json` configuration file.

• TypeError: app.get is not a function

  cause This error typically occurs if you are trying to use Fastify-specific methods directly on an application instance that hasn't been properly initialized as a Platformatic Service or if a plugin isn't correctly registered.
  fix Ensure your application is configured as a `platformatic service` and that plugins exporting Fastify routes are correctly specified in your `platformatic.json` or similar configuration under the `plugins` section. Verify the `app` object in your plugin is indeed a Fastify instance.

Warnings

• breaking Watt now requires Node.js version 22.19.0 or higher. Running on older Node.js versions will result in startup failures.
  Fix: Upgrade your Node.js environment to at least version 22.19.0. Use nvm or your preferred Node.js version manager.
• security Multiple dependencies, including `fast-jwt`, `fastify`, and `yaml`, have received security updates. Running older versions exposes applications to known vulnerabilities.
  Fix: Ensure you are on the latest `wattpm` version (3.52.2 or newer) to benefit from patched dependencies. Regularly update your `platformatic` project dependencies.
• gotcha Prior to v3.52.0, the server hostname might have implicitly defaulted to `127.0.0.1` even when unset. This behavior was corrected, and now `server.hostname` must be explicitly set if you expect it to bind to a specific interface or `0.0.0.0` for all interfaces.
  Fix: Explicitly configure `server.hostname` in your `platformatic.json` or equivalent configuration file. For example, use `"server": { "hostname": "0.0.0.0" }` to listen on all available network interfaces.
• gotcha Incorrect calculation of `--max-semi-space-size` for child processes in earlier versions could lead to suboptimal memory usage or stability issues in applications relying on multiple worker threads.
  Fix: Update to `wattpm` version 3.52.2 or newer to ensure correct V8 heap sizing for child processes. Review any custom Node.js flags for child processes to avoid conflicts.
• breaking Database views are now supported as read-only entities. While a new feature, if existing code implicitly assumed all database entities were writable and interacted with views, it might lead to unexpected read-only errors if not properly handled.
  Fix: Ensure your application logic correctly handles read-only entities when interacting with database views. Verify that write operations are not attempted on view-based entities.

Install

• npm install wattpm npm
• yarn add wattpm yarn
• pnpm add wattpm pnpm

Imports

• start
  wrong:

  const { start } = require('wattpm')

  correct:

  import { start } from 'wattpm'

  The primary programmatic entry point for launching the Watt server with a configuration. ESM is preferred for Node.js >=22.19.0 environments.
• Watt CLI
  wrong:

  import { create } from 'wattpm'

  correct:

  npx wattpm@latest create

  While `wattpm` exports a `start` function, its most common interaction pattern for developers is via the command-line interface (CLI) to scaffold new projects or manage existing ones. Direct programmatic imports for creation functionality are not exposed.
• Platformatic Types

  import type { PlatformaticService } from '@platformatic/service'

  Watt orchestrates services and runtimes. While `wattpm` itself doesn't export many types for its core runtime, developers often import types like `PlatformaticService` or `PlatformaticRuntime` from their respective `@platformatic/*` packages when building Platformatic applications.

Quickstart

This quickstart demonstrates how to programmatically start a Watt server, configure a simple Fastify service with a custom plugin, and expose a '/hello' endpoint, illustrating its core runtime capabilities.

import { start } from 'wattpm';
import { writeFileSync } from 'node:fs';
import { join } from 'node:path';

async function bootstrap() {
  const configPath = join(process.cwd(), 'platformatic.service.json');
  const config = {
    server: {
      hostname: '127.0.0.1',
      port: 0 // Assigns a random available port
    },
    service: {
      openapi: {
        url: '/documentation'
      },
      routes: {
        '/hello': {
          get: {
            handler: '$.hello'
          }
        }
      }
    },
    plugins: {
      paths: [
        join(process.cwd(), 'plugin.js')
      ]
    }
  };

  writeFileSync(configPath, JSON.stringify(config, null, 2));
  writeFileSync(join(process.cwd(), 'plugin.js'), `
    async function plugin(app) {
      app.get('/hello', async (request, reply) => {
        return { message: 'Hello from Watt!' };
      });
    }
    export default plugin;
  `);

  console.log('Starting Watt server...');
  const app = await start({ config: configPath });

  console.log(`Watt server listening on ${app.url}/hello`);
  console.log('Access documentation at ' + app.url + '/documentation');

  // To stop the server programmatically (e.g., in tests or for graceful shutdown)
  // await app.close();
}

bootstrap().catch(err => {
  console.error('Failed to start Watt server:', err);
  process.exit(1);
});