Platformatic TanStack

The Platformatic TanStack allows to run a TanStack Start application as a Platformatic Runtime application with no modifications.

Getting Started

Create or copy a TanStack Start application inside the applications, services or web folder. If you are not using autoload, you also have to explictly add the new application.

You are all set, you can now start your runtime as usual via wattpm dev or wattpm start.

Install

npm install @platformatic/tanstack

Example configuration file

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

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

Preparing for production mode

Add the following to your vite.config.ts plugins section:

process.env.NODE_ENV === 'production' &&
  nitro({
    preset: 'node-server',
    output: {
      dir: 'dist'
    }
  }),

Architecture

When starting TanStack in development mode, production mode or by using the commands property, Platformatic will choose a random port for the HTTP server and it will override any user or application setting.

HTTPS

When a TanStack 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 forwards the HTTPS options to the Vite development server used by TanStack. In production mode, Platformatic passes the same HTTPS options to the built TanStack server when it starts listening.

If the application uses application.commands, the command is responsible for creating its own HTTPS server.

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.