Platformatic Nitro

Platformatic Nitro allows you to run a Nitro application as a Platformatic Runtime application with no modifications. This includes Nitro-based applications generated by Lovable.

Both application types are supported:

• Vite applications using Nitro as a Vite plugin (via nitro/vite). In development mode, Platformatic runs the Vite development server. In production mode, it runs the Nitro server output generated by vite build.
• Standalone Nitro applications driven by the Nitro CLI. In development mode, Platformatic runs nitro dev. In production mode, it runs the Nitro server output generated by nitro build.

The application type is automatically detected. If a Vite configuration file such as vite.config.ts is present in the application root, the application is managed through Vite. Otherwise, it is managed through the Nitro CLI.

Getting Started

Create or copy a Nitro application inside the applications, services, or web folder. If you are not using autoload, you also need to explicitly add the new application.

You are all set: start your runtime as usual via wattpm dev or wattpm start.

Install

npm install @platformatic/nitro

Example configuration file

Create a watt.json in the root folder of your application with the following contents:

{
  "$schema": "https://schemas.platformatic.dev/@platformatic/nitro/3.61.1.json",
  "application": {
    "basePath": "/frontend"
  }
}

Architecture

In development mode, Platformatic starts the Vite development server for applications using Nitro as a Vite plugin, or the Nitro development server for standalone Nitro applications.

In production mode, Platformatic runs the Nitro server output generated by the build. The default output directory is .output, and the default production server entrypoint is .output/server/index.mjs. Both paths are configurable.

When using the commands property, the command is responsible for starting an HTTP server. Platformatic integrates the external application into the runtime and selects the server port.

Integrating with other Watt applications

If the Vite development server needs to be reached by other applications in the Watt mesh network, configure Vite allowed hosts in your Vite configuration:

import { nitro } from 'nitro/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [nitro()],
  server: {
    allowedHosts: ['.plt.local']
  }
})

This allows other applications inside the Platformatic mesh network to contact your development server.

Production deployment

Nitro production builds follow the standard Node.js deployment flow:

vite build # or "nitro build" for standalone Nitro applications
node .output/server/index.mjs

Deploy the full .output directory, not only .output/server/index.mjs. Nitro bundles the application server, public assets, and copied runtime dependencies inside .output.

Configuration

See the configuration page.

Runtime APIs

During application execution, Platformatic exposes runtime APIs through typed getters and setters from @platformatic/globals.

import { getApplicationId, getLogger } from '@platformatic/globals'

const applicationId = getApplicationId()
const logger = getLogger()

logger.info({ applicationId }, 'Application started')

Common APIs include:

• getLogger() to access the application logger.
• getBasePath() to read the application base path.
• getMessaging() to exchange messages with other runtime applications.
• getPrometheus() to register custom metrics in the runtime registry.
• getEvents() to listen for lifecycle events such as close.
• setCustomHealthCheck() and setCustomReadinessCheck() to customize health and readiness checks.

Direct access through globalThis.platformatic is still supported for compatibility, but deprecated. Use the typed APIs from @platformatic/globals instead.

See the Runtime APIs reference for the complete API list, error handling behavior, and examples.

Issues

If you run into a bug or have a suggestion for improvement, please raise an issue on GitHub or join our Discord feedback channel.