Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
start
✓ import { start } from 'wattpm'
✗ const { start } = require('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
✓ npx wattpm@latest create
✗ import { create } from 'wattpm'
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.
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);
});
watt --version
Debug
Known issues
breakingWatt now requires Node.js version 22.19.0 or higher. Running on older Node.js versions will result in startup failures.fixUpgrade your Node.js environment to at least version 22.19.0. Use nvm or your preferred Node.js version manager.
affects: >=3.0.0
securityMultiple dependencies, including `fast-jwt`, `fastify`, and `yaml`, have received security updates. Running older versions exposes applications to known vulnerabilities.fixEnsure you are on the latest `wattpm` version (3.52.2 or newer) to benefit from patched dependencies. Regularly update your `platformatic` project dependencies.
affects: <3.51.0 (for fast-jwt), <3.45.0 (for fastify/yaml)
gotchaPrior 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.fixExplicitly 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. affects: <3.52.0
gotchaIncorrect 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.fixUpdate 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.
affects: <3.52.2
breakingDatabase 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.fixEnsure your application logic correctly handles read-only entities when interacting with database views. Verify that write operations are not attempted on view-based entities.
affects: >=3.52.2
Errors
Common errors & fixes
Error: Cannot find module '@platformatic/service'
One of Watt's core dependencies, such as @platformatic/service or @platformatic/runtime, is missing or incorrectly installed.
fixRun `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
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.
fixExplicitly 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
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.
fixEnsure 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.
Audit
Dependencies
@platformatic/servicerequiredCore component for running individual services orchestrated by Watt.
@platformatic/runtimerequiredCore component for managing multiple services in a Platformatic Runtime environment.
@platformatic/loggerrequiredProvides fast logging capabilities (Pino) integrated into the server.