Platformatic Next

Platformatic Next allows you to run a Next.js 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, 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

npm install @platformatic/next

Example configuration file

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

{
  "$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:

{
  "$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:

{
  "$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:

{
  "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.

Configuration

See the configuration page.

Runtime APIs

During application execution, Platformatic exposes runtime APIs through typed getters and setters from @platformatic/globals.

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 instead.

See the Runtime APIs reference 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 or join our Discord feedback channel.