Skip to main content
Version: Next

Programmatic API

In many cases it's useful to start Platformatic applications using an API instead of the command line. The @platformatic/runtime API makes it simple to work with different application types (e.g. service, db, composer and runtime) without needing to know the application type a priori.


The buildServer function creates a server from a provided configuration object or configuration filename. The config can be of either Platformatic Service, Platformatic DB, Platformatic Composer or any other application built on top of Platformatic Service.

import { buildServer } from '@platformatic/runtime'

const app = await buildServer('path/to/platformatic.runtime.json')
const entrypointUrl = await app.start()

// Make a request to the entrypoint.
const res = await fetch(entrypointUrl)
console.log(await res.json())

// Do other interesting things.

await app.close()

It is also possible to customize the configuration:

import { buildServer } from '@platformatic/runtime'

const config = {
// $schema: '',
// $schema: '',
// $schema: '',
// $schema: ''
const app = await buildServer(config)

await app.start()


The loadConfig function is used to read and parse a configuration file for an arbitrary Platformatic application.

import { loadConfig } from '@platformatic/runtime'

// Read the config based on command line arguments. loadConfig() will detect
// the application type.
const config = await loadConfig({}, ['-c', '/path/to/platformatic.config.json'])

// Read the config based on command line arguments. The application type can
// be provided explicitly.
const config = await loadConfig(
['-c', '/path/to/platformatic.config.json']

// Default config can be specified.
const config = await loadConfig(
['-c', '/path/to/platformatic.config.json'],
{ key: 'value' }


The start function loads a configuration, builds a server, and starts the server. However, the server is not returned.

import { start } from '@platformatic/runtime'

await start(['-c', '/path/to/platformatic.config.json])


The startCommand function is similar to start. However, if an exception occurs, startCommand logs the error and exits the process. This is different from start, which throws the exception.

import { startCommand } from '@platformatic/runtime'

await startCommand(['-c', '/path/to/platformatic.config.json])