# Configuration

Platformatic Next 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 where the production build is stored when using `wattpm build` or `plt build`. Default: `dist`.
- **`include`**: Paths to include when deploying the application. Default: `['dist']`.
- **`commands`**: Object specifying commands to manage the application instead of Next.js 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`.

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

## `watch`

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

## `cache`

Configures an [Incremental Server Rendering cache](https://nextjs.org/docs/app/api-reference/next-config-js/incrementalCacheHandlerPath) handler or [Cache Components](https://nextjs.org/docs/app/getting-started/cache-components) cache handlers.

Supported object properties:

- **`enabled`** (`boolean` or `string`): If `false`, the cache adapter is disabled. Default: `true`.
- **`adapter`**: Adapter to use. Supported values are `valkey` and `redis` (`redis` is an alias of `valkey`).
- **`url`**: URL of the Valkey/Redis server.
- **`prefix`**: Prefix for all cache keys.
- **`maxTTL`**: Maximum key lifetime (seconds). If Next.js `revalidate` is greater than this value, key expiry is refreshed while accessed at least every `maxTTL` seconds. Default: `604800` (one week).
- **`cacheComponents`**: Use [Cache Components](https://nextjs.org/docs/app/getting-started/cache-components) instead of ISR cache handlers. Alternative to `cacheComponents: true` in `next.config.js`. Supported from Next.js 16.0.
- **`ignoreNextConfig`**: Ignore cache-related values already defined in `next.config.js` and prefer Platformatic configuration.
- **`remote`**: Optional configuration for the [`"use cache: remote"`](https://nextjs.org/docs/app/api-reference/directives/use-cache-remote) directive. When present, a separate `cacheHandlers.remote` is registered alongside `cacheHandlers.default`. All properties are optional and inherit from the parent `cache` config when omitted. Requires `cacheComponents: true`. Supported object properties:
  - **`url`**: URL of the Valkey/Redis server for remote cache entries.
  - **`prefix`**: Prefix for remote cache keys.
  - **`maxTTL`**: Maximum key lifetime (seconds) for remote cache entries.

  Example using separate Valkey instances for default and remote cache:

  ```json
  {
    "cache": {
      "adapter": "valkey",
      "url": "valkey://localhost:6379",
      "cacheComponents": true,
      "remote": {
        "url": "valkey://remote-server:6379",
        "prefix": "plt:remote",
        "maxTTL": 3600
      }
    }
  }
  ```

  In this configuration, `"use cache"` entries are stored on `localhost:6379` while `"use cache: remote"` entries go to `remote-server:6379` with a separate prefix and a 1-hour TTL. If `remote.url` is omitted, both handlers share the same Valkey instance but use different key namespaces to avoid collisions.

  When runtime metrics are enabled, Cache Components exposes these Prometheus counters:

  - **`next_components_cache_valkey_hit_count`**: Successful reads from the default Cache Components cache.
  - **`next_components_cache_valkey_miss_count`**: Missing, invalid, or failed reads from the default Cache Components cache.
  - **`next_remote_components_cache_valkey_hit_count`**: Successful reads from the remote Cache Components cache.
  - **`next_remote_components_cache_valkey_miss_count`**: Missing, invalid, or failed reads from the remote Cache Components cache.

  The counters use the runtime's standard application, worker, and configured static labels. The remote counters are registered only when `remote` is configured. Hit ratios can be calculated in PromQL from the corresponding hit and miss counters.

## `next`

Configures Next.js. Supported object properties:

- **`trailingSlash`**: Enables [trailingSlash](https://nextjs.org/docs/pages/api-reference/config/next-config-js/trailingSlash) in `next.config.js`.
- **`useExperimentalAdapter`**: Enables [`experimental.adapterPath`](https://nextjs.org/docs/app/api-reference/config/next-config-js/adapterPath) integration to modify `next.config.js` automatically. For Next.js versions earlier than 16, this setting is ignored.

  Add this to your `next.config.js`:

  ```js
  import { getAdapterPath } from '@platformatic/next'

  module.exports = {
    experimental: {
      adapterPath: getAdapterPath()
    }
  }
  ```

- **`standalone`**: Set to `true` when using [Next.js standalone mode](https://nextjs.org/docs/pages/api-reference/config/next-config-js/output). This also enables the Next-specific application command used to pack a self-contained bundle for deployment. Run `wattpm help` in your project to see the available `<app-id>:pack` command.
- **`https`**: Enables HTTPS in development mode when Platformatic starts Next.js with the default development command.
  - **`enabled`** (`boolean` or `string`): Enables Next.js experimental HTTPS.
  - **`key`**: Path (relative to the application root) to the HTTPS private key file.
  - **`cert`**: Path (relative to the application root) to the HTTPS certificate file.
  - **`ca`**: Path (relative to the application root) to the HTTPS certificate authority file.
- **`imageOptimizer`**: Configures Next.js Image Optimizer mode. When enabled, this service runs only the `/_next/image` API endpoint (instead of the full Next.js app). Supported object properties:
  - **`enabled`**: Boolean flag to enable the mode. Default: `false`.
  - **`fallback`**: URL or service name used to fetch original images:
    - Full URL (for example, `https://example.com`)
    - Local service name (for example, `backend`), resolved to `http://backend.plt.local`
  - **`storage`**: Queue storage backend:
    - `{ "type": "memory" }` (default)
    - `{ "type": "filesystem", "path": ".next/cache/image-optimizer" }`
    - `{ "type": "valkey", "url": "redis://localhost:6379/0", "prefix": "my-app:" }` (or `redis`)
  - **`timeout`** (`number` or `string`): Timeout in milliseconds used for image fetch/optimization operations. Default: `30000`.
  - **`maxAttempts`** (`number` or `string`): Maximum retry attempts for optimization jobs. Default: `3`.

## Skew protection

When `PLT_DEPLOYMENT_ID` is set during the build, Platformatic sets Next.js `deploymentId` automatically unless it is already configured. You can also configure it directly in `next.config.js`:

```js
module.exports = {
  deploymentId: process.env.PLT_DEPLOYMENT_ID
}
```


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