# Platformatic Remix

The Platformatic Remix allows to run a [Remix](https://remix.run/) application as a Platformatic Runtime application with no modifications.

## Getting Started

Create or copy a Remix 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/remix
```

## 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/remix/2.0.0.json",
  "application": {
    "basePath": "/frontend"
  }
}
```

## Architecture

When running in development mode, the Vite development server instrumented with [@remix-run/dev](https://www.npmjs.com/package/@remix-run/dev) 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 application 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 application 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 application in the runtime.

## Skew protection

Remix uses a user-provided Vite configuration. To tag assets, add the shared plugin:

```ts
import { platformaticSkewPlugin } from '@platformatic/vite/skew-plugin'

export default defineConfig({
  plugins: [platformaticSkewPlugin()]
})
```

The plugin is enabled when `PLT_DEPLOYMENT_ID` is set during the build.

## HTTPS

When a Remix application is the Watt entrypoint, configure HTTPS in the runtime `server.https` object:

```json
{
  "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 Remix. In production mode, Platformatic uses the same HTTPS options for the Fastify server that serves the built Remix application.

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

### Using custom commands

Due to [`CVE-2025-24010`](https://github.com/vitejs/vite/security/advisories/GHSA-vg6x-rcgg-rjx6), you need to set:

```js
{
  ...
  "server": {
    "allowedHosts": [".plt.local"]
  }
}
```

This will allow other applications inside the platformatic mesh network to contact your Vite server.

## Using when the entrypoint is a Platformatic Gateway

To properly work when using with in application where the entrypoint is a Platformatic Gateway, you need to adjust your `vite.config.ts` file to
properly set the Vite's `base` property and the `remix.basename` property as follows:

```js
import { vitePlugin as remix } from '@remix-run/dev'
import { defineConfig } from 'vite'
import { getBasePath } from '@platformatic/globals'

export default defineConfig({
  base: getBasePath({ throwOnMissing: false }) ?? '/',
  /* ... */
  plugins: [
    remix({
      basename: getBasePath({ throwOnMissing: false }) ?? '/'
      /* ... */
    })
  ]
})
```

## Configuration

See the [configuration](/docs/latest/reference/remix/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).