# Platformatic Next

Platformatic Next allows you to run a [Next.js](https://nextjs.org/) application as a Platformatic Runtime application with no modifications. It also provides additional features such as an Image Optimizer mode for optimizing images on-the-fly.

## Getting Started

Create or copy a Next.js application inside the `applications`, `services`, or `web` folder. If you are not using [`autoload`](/docs/latest/reference/runtime/configuration/#autoload), you also need to explicitly add the new application.

You are all set: start your runtime as usual via `wattpm dev` or `wattpm start`.

## Install

```bash
npm install @platformatic/next
```

## Example configuration file

Create a `watt.json` in the root folder of your application with the following contents:

```json
{
  "$schema": "https://schemas.platformatic.dev/@platformatic/next/3.38.1.json",
  "application": {
    "basePath": "/frontend"
  }
}
```

### Example with Image Optimizer mode (behind Gateway route matching)

Use this mode when you only need the `/_next/image` endpoint and want to expose it through a Gateway entrypoint.

In this setup:

- Gateway forwards only `GET /_next/image` to the optimizer service using `proxy.routes`
- all other routes can be forwarded to a regular frontend service
- relative image URLs (for example `/hero.png`) are fetched from the local fallback service via service discovery

`services/gateway/platformatic.json`:

```json
{
  "$schema": "https://schemas.platformatic.dev/@platformatic/gateway/3.0.0.json",
  "gateway": {
    "applications": [
      {
        "id": "optimizer",
        "proxy": {
          "prefix": "/",
          "routes": ["/_next/image"],
          "methods": ["GET"]
        }
      },
      {
        "id": "fallback",
        "proxy": {
          "prefix": "/"
        }
      }
    ]
  }
}
```

`services/optimizer/platformatic.json`:

```json
{
  "$schema": "https://schemas.platformatic.dev/@platformatic/next/3.38.1.json",
  "next": {
    "imageOptimizer": {
      "enabled": true,
      "fallback": "fallback"
    }
  }
}
```

## Architecture

When starting Next.js in development mode, production mode, or by using the `commands` property, Platformatic selects a random internal port for the Next.js HTTP server and overrides any user or application setting.

## HTTPS

When a Next.js application is the Watt entrypoint, configure HTTPS in the runtime `server.https` object:

```json
{
  "server": {
    "https": {
      "key": { "path": "./certs/server.key" },
      "cert": { "path": "./certs/server.crt" }
    }
  }
}
```

In development mode, Platformatic maps `server.https` to Next.js' experimental HTTPS development server options.

Next.js does not support HTTPS in production mode with `next start`. To run a production Next.js application over HTTPS, terminate TLS before Watt or use a custom command/server that creates its own HTTPS server.

## Features

- **Image Optimizer**: Run a standalone image optimization service. See [Image Optimizer](/docs/latest/reference/next/image-optimizer/).

## Configuration

See the [configuration](/docs/latest/reference/next/configuration/) page.


## Runtime APIs

During application execution, Platformatic exposes runtime APIs through typed getters and setters from [`@platformatic/globals`](/docs/latest/reference/runtime/globals/).

```js
import { getApplicationId, getLogger } from '@platformatic/globals'

const applicationId = getApplicationId()
const logger = getLogger()

logger.info({ applicationId }, 'Application started')
```

Common APIs include:

- `getLogger()` to access the application logger.
- `getBasePath()` to read the application base path.
- `getMessaging()` to exchange messages with other runtime applications.
- `getPrometheus()` to register custom metrics in the runtime registry.
- `getEvents()` to listen for lifecycle events such as `close`.
- `setCustomHealthCheck()` and `setCustomReadinessCheck()` to customize health and readiness checks.

Direct access through `globalThis.platformatic` is still supported for compatibility, but deprecated. Use the typed APIs from [`@platformatic/globals`](/docs/latest/reference/runtime/globals/) instead.

See the [Runtime APIs reference](/docs/latest/reference/runtime/globals/) for the complete API list, error handling behavior, and examples.


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