Skip to main content
Version: Next

Platformatic Nuxt

Platformatic Nuxt allows you to run a Nuxt application as a Platformatic Runtime application with no modifications.

Getting Started​

Create or copy a Nuxt 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/nuxt

Example configuration file​

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

{
  "$schema": "https://schemas.platformatic.dev/@platformatic/nuxt/3.52.4.json",
  "application": {
    "basePath": "/frontend"
  }
}

Architecture​

When running in development mode, Platformatic starts the Nuxt development server. Nuxt uses Vite internally for development, hot module replacement, and module transforms.

When running in production mode, Platformatic runs the Nuxt/Nitro server output generated by nuxt build. The default output directory is .output, and the production server entrypoint is .output/server/index.mjs.

Nuxt uses Vite internally, but Platformatic Nuxt is not a plain Vite application. Development, build, and production lifecycle are managed through Nuxt and Nitro.

When using the commands property, the command is responsible for starting an HTTP server. Platformatic will integrate the external application in the runtime and select the server port used by the runtime.

Integrating with other Watt applications​

If the Nuxt development server needs to be reached by other applications in the Watt mesh network, configure Vite allowed hosts in nuxt.config:

export default defineNuxtConfig({
  vite: {
    server: {
      allowedHosts: ['.plt.local']
    }
  }
})

This allows other applications inside the Platformatic mesh network to contact your Nuxt development server.

Production deployment​

Nuxt production builds are powered by Nitro. The standard Node.js deployment flow is:

nuxt build
node .output/server/index.mjs

Deploy the full .output directory, not only .output/server/index.mjs. Nitro bundles the application server, public assets, and any copied runtime dependencies inside .output.

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.