# Platformatic Nitro

Platformatic Nitro allows you to run a [Nitro](https://nitro.build/) application as a Platformatic Runtime application with no modifications. This includes Nitro-based applications generated by [Lovable](https://lovable.dev/).

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`](/docs/latest/reference/runtime/configuration/#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

```bash
npm install @platformatic/nitro
```

## Example configuration file

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

```json
{
  "$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:

```js
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:

```bash
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](/docs/latest/reference/nitro/configuration/) page.


## Runtime APIs

During application execution, Platformatic exposes runtime APIs through typed getters and setters from [`@platformatic/globals`](/docs/latest/reference/runtime/globals/).

```js
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`](/docs/latest/reference/runtime/globals/) instead.

See the [Runtime APIs reference](/docs/latest/reference/runtime/globals/) 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](https://github.com/platformatic/platformatic/issues/new).