Configuration

Platformatic Node is configured with a configuration file. It supports the use of environment variables as setting values with configuration placeholders.

application

Supported object properties:

• basePath: Service proxy base path when exposing this application in a gateway when setting the proxy property. If not specified, the application will be exposed on the application or a value specified in the application code via platformatic.setBasePath().
• outputDirectory: The subdirectory where production build is stored at when using wattpm build or plt build. The default is dist.
• include: The paths to include when deploying the application. The default is ['dist'].
• commands: An object specifying the commands to manage the application instead of directly executing the application entrypoint. Supported commands are:
  • install: The command to execute to install the application dependencies. The default is npm ci --omit-dev.
  • build: The command to execute to build the application.
  • development: The command to execute to start the application in development mode.
  • production: The command to execute to start the application in production mode.

node

Configures Node. Supported object properties:

• main: The entrypoint of the application. This is only needed if the main property is not set in the application package.json file.
• absoluteUrl: If set to true, then the application will receive the full URL from a Platformatic Gateway. The default is false.
• dispatchViaHttp: If set to true, then the application will serve requests coming from the mesh network via a TCP port.
• disableBuildInDevelopment: If set to true, it will not automatically build an application in development mode.
• disablePlatformaticInBuild: If set to true, then no Platformatic code will be started when running the build command.
• hasServer: If set to false, then Platformatic Node will treat the application as a background application which doesn't expose any HTTP port.

logger

Configures the logger, see the runtime documentation.

server

Configures the HTTP server, see the runtime documentation.

watch

Manages watching of the application, see the service documentation.

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.