Platformatic Vite
The Platformatic Vite allows to run a Vite application as a Platformatic Runtime service with no modifications.
Getting Started
Create or copy a Vite application inside the web
or services
folder. If you are not using autoload
, you also have to explictly add the new service.
You are all set, you can now start your runtime as usual via wattpm dev
or plt start
.
Example configuration file
{
"$schema": "https://schemas.platformatic.dev/@platformatic/vite/2.0.0.json",
"application": {
"basePath": "/frontend"
}
}
Architecture
When running in development mode, the Vite development server is run a in worker thread in the same process of the Platformatic runtime. The server port is chosen randomly and it will override any user setting.
When running in production mode, a custom Fastify server will serve the built application. The service is run a in worker thread in the same process of the Platformatic runtime and it will not start a TCP server unless it's the runtime entrypoint.
In both modes if the service uses the commands
property then it's responsible to start a HTTP server. The Platformatic runtime will modify the server port replacing it with a random port and then it will integrate the external service in the runtime.
If the application is a SSR application, it is only supported if using @fastify/vite
.
Using custom commands and @fastify/vite
Due to CVE-2025-24010
, you need to set:
{
...
"server": {
"allowedHosts": [".plt.local"]
}
}
This will allow other services inside the platformatic mesh network to contact your Vite server.
Configuration
See the configuration page.
API
During service execution some APIs are made available in the globalThis.platformatic
object.
globalThis.platformatic.setBasePath(path)
: This function can be use to override the base path for the service. If not properly configure in the composer, this can make your application unaccessible.globalThis.platformatic.serviceId
: The id of the service.globalThis.platformatic.workerId
: The id of the service worker.globalThis.platformatic.root
: The root directory of the service.globalThis.platformatic.basePath
: The base path of the service in the composer.globalThis.platformatic.logLevel
: The log level configured for the service.globalThis.platformatic.events.on('close')
: This event is emitted when the process is being closed. A listener should be installed to perform a graceful close, which must finish in 10 seconds. If there is no listener, the process will be terminated by invokingprocess.exit(0)
.globalThis.platformatic.setCustomHealthCheck(fn)
: This function can be use to set a custom healthcheck function for the service.
Custom Metrics
Custom metrics can be registered and exported by accessing the same Prometheus registry that the rest of the Platformatic runtime is using via globalThis.platformatic.prometheus.registry
.
In order to ensure the maximum compatibility the client package (prom-client
) is available in globalThis.platformatic.prometheus.client
.
Here it is an example of how to register a custom metric:
const { client, registry } = globalThis.platformatic.prometheus
// Register the metric
const customMetrics = new client.Counter({ name: 'custom', help: 'Custom Description', registers: [registry] })
// ...
// Later increase the value
customMetrics.inc(123)
Remember that it is a good practice to register metrics as soon as possible during the boot phase.
Typings for the API
In order to get full Typescript support for the API above, you can install the @platformatic/globals
package and get an alternative, typed, access to the globalThis.platformatic
object.
The usage of the package is straight-forward:
import { getGlobal } from '@platformatic/globals`
const pltApi = getGlobal()
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.
Custom Healthcheck
Custom health check can be defined to provide more specific and detailed information about the health of your service, in case the default healthcheck for the service itself is not enough and you need to add more checks for the service dependencies.
This can be done by using the setCustomHealthCheck
method available on the globalThis.platformatic
object, and run it as a platformatic service.
Here is an example of how to set a custom health check:
app.js
import fastify from 'fastify'
export function create () {
const app = fastify()
globalThis.platformatic.setCustomHealthCheck(async () => {
return Promise.all([
// Check if the database is reachable
app.db.query('SELECT 1'),
// Check if the external service is reachable
fetch('https://payment-service.com/status')
])
})
app.get('/', (req, res) => {
res.send('Hello')
})
return app
}
platformatic.json
{
"$schema": "https://schemas.platformatic.dev/@platformatic/node/2.51.0.json"
}
package.json
{
"type": "module",
"name": "service-node",
"version": "1.0.0",
"main": "app.js",
"scripts": {
"start": "platformatic start"
},
"dependencies": {
"fastify": "^5.0.0",
"@platformatic/node": "^2.48.0"
}
}