# Configuration

Platformatic Nitro is configured through a configuration file. It supports environment variables as setting values with [configuration placeholders](#configuration-placeholders).

## `application`

Supported object properties:

- **`basePath`**: Service proxy base path when exposing this application in a [gateway](/docs/latest/reference/gateway/configuration/) with the `proxy` property. If not specified, the application is exposed on `/$ID` (where `$ID` is the application ID), or on a value specified in application code via `platformatic.setBasePath()`.
- **`outputDirectory`**: Subdirectory Platformatic includes in deployments and uses as the default location of the Nitro production output. Default: `.output`.
- **`include`**: Paths to include when deploying the application. Defaults to the effective Nitro output directory.
- **`commands`**: Object specifying commands to manage the application instead of Nitro defaults:
  - **`install`**: Command to install application dependencies. Default: `npm ci --omit-dev`.
  - **`build`**: Command to build the application.
  - **`development`**: Command to start the application in development mode.
  - **`production`**: Command to start the application in production mode.
- **`changeDirectoryBeforeExecution`**: If `true`, change the current working directory to the application root before running any of the commands above. Default: `false`.
- **`preferLocalCommands`**: If `true`, resolve non-absolute commands from the application's `node_modules/.bin` before checking the current working directory. Default: `true`.

## `nitro`

Configures Nitro-specific Platformatic behavior.

Supported object properties:

- **`outputDirectory`**: Directory containing the Nitro production output. Defaults to `application.outputDirectory`, which is `.output` unless configured.
- **`entrypoint`**: Server entrypoint relative to `nitro.outputDirectory`. Default: `server/index.mjs`.

:::note
Platformatic Nitro uses `nitro.outputDirectory` and `nitro.entrypoint` to locate the generated server. When changing the output directory, configure Nitro's `output.dir` to write to the same path. Unless explicitly configured, `application.include` follows the effective Nitro output directory.
:::

## `vite`

Configures Vite options used by the development server when Nitro is used as a Vite plugin. Platformatic Nitro supports `configFile` and `devServer` from the [Platformatic Vite configuration](/docs/latest/reference/vite/configuration/#vite). Set `configFile` to `false` to force standalone Nitro mode.

This is useful for development server settings such as allowing mesh-network hostnames:

```json
{
  "vite": {
    "devServer": {
      "strict": false
    }
  }
}
```

## `logger`

Configures the `logger`. See [runtime logger](/docs/latest/reference/runtime/configuration/#logger).

## `server`

Configures the HTTP server. See [runtime server](/docs/latest/reference/runtime/configuration/#server).

`server.http2` is not supported because Nitro creates its own HTTP server. In standalone Nitropack development, TLS keys and certificates must each use a single `{ "path": "..." }` value.

## `watch`

Manages watching of the application. See [application watch](/docs/latest/reference/service/configuration/#watch).


## `runtime`

The `runtime` property allows you to embed runtime configuration directly in your application's configuration file. This is useful when you want to configure runtime-level settings specific to this application without needing a separate runtime configuration file.

See the [runtime configuration](/docs/latest/reference/runtime/configuration/) documentation for details on each property.

### Available properties

The following runtime properties can be configured at the application level:

- [**`preload`**](/docs/latest/reference/runtime/configuration/#preload): Files to load before the application code.
- [**`workers`**](/docs/latest/reference/runtime/configuration/#workers): Worker configuration for this application.
- [**`logger`**](/docs/latest/reference/runtime/configuration/#logger): Logger configuration.
- [**`server`**](/docs/latest/reference/runtime/configuration/#server): Server configuration (hostname, port, HTTPS, HTTP/2).
- [**`watch`**](/docs/latest/reference/runtime/configuration/#watch): Enable/disable file watching.
- [**`health`**](/docs/latest/reference/runtime/configuration/#health): Health check configuration.
- [**`telemetry`**](/docs/latest/reference/runtime/configuration/#telemetry): OpenTelemetry configuration.
- [**`undici`**](/docs/latest/reference/runtime/configuration/#undici): Undici HTTP client configuration.
- [**`httpCache`**](/docs/latest/reference/runtime/configuration/#httpcache): HTTP caching configuration.
- [**`metrics`**](/docs/latest/reference/runtime/configuration/#metrics): Prometheus metrics configuration.
- [**`gracefulShutdown`**](/docs/latest/reference/runtime/configuration/#gracefulshutdown): Shutdown timeout settings.
- [**`startTimeout`**](/docs/latest/reference/runtime/configuration/#starttimeout): Application start timeout.
- [**`restartOnError`**](/docs/latest/reference/runtime/configuration/#restartonerror): Restart behavior on errors.
- [**`compileCache`**](/docs/latest/reference/runtime/configuration/#compilecache): Node.js compile cache settings.

### Application-specific overrides

Within the `runtime` property, you can also use the `application` sub-property to configure application-specific settings that would normally be set in the runtime's [`applications`](/docs/latest/reference/runtime/configuration/#applications) array:

- **`workers`**: Worker count for this application.
- **`health`**: Health check settings for this application.
- **`env`**: Environment variables.
- **`envfile`**: Path to an `.env` file.
- **`sourceMaps`**: Enable source maps.
- **`preload`**: Files to preload.
- **`nodeOptions`**: Node.js options.
- **`execArgv`**: Arguments passed to worker threads.
- **`permissions`**: File system permissions.
- **`telemetry`**: Application-specific telemetry instrumentations.
- **`compileCache`**: Compile cache settings.

### Example

The following example uses `@platformatic/next`, but the same configuration applies to other capabilities like `@platformatic/node`, `@platformatic/astro`, `@platformatic/vite`, and `@platformatic/remix`.

```json
{
  "$schema": "https://schemas.platformatic.dev/@platformatic/next/3.31.0.json",
  "runtime": {
    "logger": {
      "level": "debug"
    },
    "workers": {
      "dynamic": true,
      "minimum": 1,
      "maximum": 4
    },
    "application": {
      "env": {
        "CUSTOM_VAR": "value"
      },
      "execArgv": ["--max-old-space-size=4096"]
    }
  }
}
```



# 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).