# Platformatic Node

The Platformatic Node allows to run a [Fastify](https://fastify.io/), [Express](https://expressjs.com/), [Koa](https://koajs.com/#) or plain Node application as a Platformatic Runtime application with no modifications.

## Getting Started

Create or copy your application inside the `applications`, `services` or `web` folder. If you are not using [`autoload`](/docs/latest/reference/runtime/configuration/#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

```bash
npm install @platformatic/node
```

## Example configuration file

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

```json
{
  "$schema": "https://schemas.platformatic.dev/@platformatic/node/2.0.0.json",
  "application": {
    "basePath": "/frontend"
  }
}
```

## Specify application info

Some info can be specified for Node.js applications through the [`@platformatic/globals` Runtime APIs](/docs/latest/reference/runtime/globals/). Currently, a few lines of code must be added.

### OpenAPI and GraphQL schema

It's possible for the node applications to expose the OpenAPI or GraphQL schemas, if any.
This can be done adding few lines of code, e.g. for fastify:

```javascript
import { getLogger, setOpenapiSchema } from '@platformatic/globals'
import fastify from 'fastify'
import fastifySwagger from '@fastify/swagger'

export async function build () {

  const server = fastify({
    loggerInstance: getLogger()
  })

  await server.register(fastifySwagger, {
    openapi: {
      openapi: '3.0.0',
      info: {
        title: 'Test Fastify API',
        description: 'Testing the Fastify swagger API',
        version: '0.1.0'
      },
     }
  })

  server.addHook('onReady', async () => {
    const schema = server.swagger()
    setOpenapiSchema(schema)
  })
```

### Connection String

It's possible to specify if a node application uses a connection string (and which one).
This is useful to map which application uses which database and to potentialy track database changes.

```javascript
import { setConnectionString } from '@platformatic/globals'
import { createServer } from 'node:http'

setConnectionString('postgres://dbuser:dbpass@mydbhost/apidb')

const server = createServer((_req, res) => {
  res.end(JSON.stringify({ ok: true }))
})

server.listen(0)
```

### Scheduled tasks

Node applications can register scheduled tasks with [Watt's scheduler](/docs/latest/guides/scheduler/) by exporting
`scheduledTasks` and `tasks` at the top level of their entrypoint. `scheduledTasks` maps cron expressions to one or
more task names, and `tasks` maps those names to handlers:

```js
export const scheduledTasks = {
  '0 */5 * * * *': ['cleanup']
}

export const tasks = {
  async cleanup ({ scheduledTime, app }) {
    // scheduledTime is the invocation timestamp in milliseconds.
    // app is the application returned by create() or build(), or the Node HTTP server.
  }
}
```

Watt registers each cron expression as an application scheduler job and invokes its handlers through the Runtime.
Handlers in a task group run concurrently. A failed handler marks the group as failed and lets the Runtime apply its
configured retry policy.

## Architecture

If your server entrypoint exports a `create` function, then Platformatic Node will execute it and then will wait for it to return a server object. In this situation the server will be used without starting a TCP server. The TCP server is started if the application is the runtime entrypoint.

If your server entrypoint does not export a function, then Platformatic runtime will execute the function and wait for a TCP server to be started.

In both cases, the listening port is always modified and chosen randomly, overriding any user or application setting.

If the application uses the `commands` property then it's always responsible to start a HTTP server and the `create` functions are not supported anymore.

In all cases, Platformatic runtime will modify the server port replacing it with a random port and then it will integrate the external application in the runtime.

If your application entrypoint exports a `create` or `build` function that returns an object with `isBackgroundApplication` set to `true`, then Platformatic Node will treat the application as a background application which doesn't expose any HTTP port. If the returned object has a `close` function, it will be called upon application shutdown as `close(app)`, where `app` is the returned object.

Alternatively, your application entrypoint can export a `hasServer` variable set to `false`, or you can set the `node.hasServer` property to false in your `watt.json` file. To gracefully shut down an application with `hasServer=false`, you may export a `close` function that will be called upon application shutdown.

## HTTPS

When a `@platformatic/node` application is the Watt entrypoint, configure HTTPS in the runtime `server.https` object:

```json
{
  "$schema": "https://schemas.platformatic.dev/wattpm/3.0.0.json",
  "entrypoint": "api",
  "server": {
    "hostname": "127.0.0.1",
    "port": 3042,
    "https": {
      "key": { "path": "./certs/server.key" },
      "cert": { "path": "./certs/server.crt" }
    }
  },
  "applications": [
    {
      "id": "api",
      "path": "./services/api"
    }
  ]
}
```

Use `getAdditionalServerOptions()` in your Node.js application and pass the returned options to `node:https.createServer()`:

```js
import { getAdditionalServerOptions } from '@platformatic/globals'
import { createServer } from 'node:https'

const server = createServer(getAdditionalServerOptions(), (req, res) => {
  res.end('ok')
})

server.listen(0)
```

Watt reads `key` and `cert` file paths before loading the application, so `getAdditionalServerOptions()` returns the sanitized TLS options that `node:https` expects. `reuseTcpPorts` remains enabled by default and HTTPS servers use `SO_REUSEPORT` when the current Node.js version and operating system support it.

## Example applications entrypoints

### Fastify with build function

```js
import { getBasePath, getLogLevel } from '@platformatic/globals'
import fastify from 'fastify'

export function create () {
  const app = fastify({
    logger: { level: getLogLevel({ throwOnMissing: false }) ?? 'info' }
  })

  const prefix = getBasePath({ throwOnMissing: false }) ?? ''

  app.get(`${prefix}/env`, async () => {
    return { production: process.env.NODE_ENV === 'production' }
  })

  return app
}
```

### Express with no build function

```js
import { getBasePath } from '@platformatic/globals'
import express from 'express'

const app = express()

const prefix = getBasePath({ throwOnMissing: false }) ?? ''

app.get(`${prefix}/env`, (req, res) => {
  res.send({ production: process.env.NODE_ENV === 'production' })
})

app.listen(3000)
```

### Background only application

```js
export async function create () {
  const id = setInterval(() => console.log('alive'), 10_000)

  return {
    isBackgroundApplication: true,
    id,
    async close (app) {
      clearInterval(app.id)
    }
  }
}
```

Alternatively, for modules that start background work when imported, export `hasServer` as `false`:

```js
import { getMessaging } from '@platformatic/globals'

export const hasServer = false

const messaging = getMessaging()
messaging.handle('ping', () => 'pong')

const timeoutId = setTimeout(() => console.log('done'), 10_000)

// Optionally provide a close function
export async function close () {
  clearTimeout(timeoutId)
}
```

## Handling Application Shutdown

When your Node.js application needs to gracefully shut down, Platformatic provides several mechanisms to ensure resources are properly cleaned up:

### `close` Function

Export a `close` function from your application entry point to handle cleanup when the application shuts down:

```js
// Store references to resources that need cleanup
let server
let database

export async function close () {
  console.log('Cleaning up...')

  // Clean up your resources
  if (database) {
    await database.close()
  }
  if (server) {
    await server.close()
  }

  console.log('Application closed gracefully')
}
```

### `close` Event Handler

Alternatively, you can register a close event handler using the Platformatic events getter. `getEvents()` returns `PlatformaticEvents`, an `EventEmitter` with an additional `emitAndNotify(event, ...args)` method for emitting locally and notifying the runtime.

```js
import { getEvents } from '@platformatic/globals'

const events = getEvents()
events.on('close', () => {
  console.log('Received close event, cleaning up...')

  // Perform your cleanup operations
})
```

### `closeServer`

When using `NodeCapability` programmatically, call `closeServer()` to close the application's listening HTTP server without stopping the capability. It returns `undefined` when no server is listening, otherwise it returns a promise that resolves when the server is closed.

### `Symbol.asyncDispose`

If your `create` or `build` factory returns an object with a `Symbol.asyncDispose` method, Platformatic will automatically call it during shutdown:

```js
import { createServer } from 'node:http'

export function create () {
  const server = createServer((_, res) => {
    res.end('Hello')
  })

  return {
    listen (...args) {
      return server.listen(...args)
    },
    async [Symbol.asyncDispose] () {
      // Perform your cleanup operations
      await new Promise((resolve, reject) => {
        server.close(err => (err ? reject(err) : resolve()))
      })
    }
  }
}
```

This follows the [TC39 Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management) convention. The `Symbol.asyncDispose` method is called after the `close` event is emitted and before the server is closed.

### Fastify Applications

Fastify applications are handled automatically by Platformatic, but custom cleanup logic can still be implemented using the other mechanisms above if needed.

### General behavior

Platformatic Node handles closing the main application components:

- **Applications with `create` function**: It will invoke the `close` method on the server returned by the function.
- **Applications without `create` function**: It will invoke the `close` method on the first `node:http` server that listened on a TCP port.

However, **additional resources must be manually closed** using the mechanisms described above, otherwise the application will hang during shutdown and eventually timeout.

In applications launched via custom commands only the `close` event handler is available for cleanup and the `close` function is ignored.

:::warn
If your application needs to clean up some shared states (connection pool, etc), you must export a `close` function, handle the `close` event, or implement `Symbol.asyncDispose` on the object returned by your factory. If you don't, Platformatic will log a warning message suggesting you implement proper cleanup to avoid exit timeouts. The exception is Fastify.
:::

### Typescript

The Platformatic Node allows to run Typescript application with the use of custom commands via the `commands` property.

To make Typescript work in development mode, setup a `commands.development` value which will start Node.js with a TypeScript loader.

When configuring production mode instead, you have to configure both the `commands.build` and `commands.production` values. The former will be used to compile your application, while the latter will be used to start it.

A complete typical setup for the application `watt.json` file will be something like this:

```
{
  "$schema": "https://schemas.platformatic.dev/@platformatic/node/2.9.1.json",
  "application": {
    "commands": {
      "development": "node --import tsx server.ts",
      "build": "tsc",
      "production": "node dist/server.js"
    }
  }
}
```

Watt supports setting up `npm run ...` commands so you can reuse your existing npm scripts flow.

## Configuration

See the [configuration](/docs/latest/reference/node/configuration/) page.


## Runtime APIs

During application execution, Platformatic exposes runtime APIs through typed getters and setters from [`@platformatic/globals`](/docs/latest/reference/runtime/globals/).

```js
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`](/docs/latest/reference/runtime/globals/) instead.

See the [Runtime APIs reference](/docs/latest/reference/runtime/globals/) 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](https://github.com/platformatic/platformatic/issues/new).