Configuration

Platformatic Nitro is configured through a configuration file. It supports environment variables as setting values with configuration placeholders.

application

Supported object properties:

• basePath: Service proxy base path when exposing this application in a gateway 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. Set configFile to false to force standalone Nitro mode.

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

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

logger

Configures the logger. See runtime logger.

server

Configures the HTTP server. See runtime 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.

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 documentation for details on each property.

Available properties

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

• preload: Files to load before the application code.
• workers: Worker configuration for this application.
• logger: Logger configuration.
• server: Server configuration (hostname, port, HTTPS, HTTP/2).
• watch: Enable/disable file watching.
• health: Health check configuration.
• telemetry: OpenTelemetry configuration.
• undici: Undici HTTP client configuration.
• httpCache: HTTP caching configuration.
• metrics: Prometheus metrics configuration.
• gracefulShutdown: Shutdown timeout settings.
• startTimeout: Application start timeout.
• restartOnError: Restart behavior on errors.
• 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 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.

{
  "$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 or join our Discord feedback channel.