# Configuration

Platformatic Astro is configured with a configuration file. It supports the use
of 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/) when setting the `proxy` property. If not specified, the application will be exposed on the `/$ID` (where `$ID` is the application ID) id 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 using the Astro defaults. 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. This currently does not work due to due to [`CVE-2025-24010`](https://github.com/vitejs/vite/security/advisories/GHSA-vg6x-rcgg-rjx6).
- **`changeDirectoryBeforeExecution`**: If set to `true`, change the current working directory to the application root before running any of the commands above. The default is `false`.
- **`preferLocalCommands`**: If set to `true`, resolve non-absolute commands from the application's `node_modules/.bin` before checking the current working directory. The default is `true`.

## `logger`

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

## `server`

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

## `watch`

Manages watching of the application, see the [application](/docs/latest/reference/service/configuration/#watch) 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](/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).