---
url: https://medicus.js.org/integrations/h3.md
description: >-
  Add a health check endpoint to H3 1 or 2 apps and Nitro route files with one
  event handler.
---

# H3 / Nitro&#x20;

`createH3HealthCheckHandler` returns a plain event handler that works with H3 1 and H3 2, so the same handler runs in Nitro 2 and Nitro 3. Checkers receive the `H3Event` as their context.

In Nitro, export it from a route file:

```ts
// server/routes/health.get.ts
import { HealthStatus } from 'medicus';
import { createH3HealthCheckHandler } from 'medicus/h3';

export default createH3HealthCheckHandler({
  checkers: {
    database(event) {
      console.log(event.path);
      return HealthStatus.HEALTHY;
    }
  }
});
```

In an H3 app, register it as a route:

```ts
import { H3 } from 'h3';
import { createH3HealthCheckHandler } from 'medicus/h3';

const app = new H3().get('/health', createH3HealthCheckHandler());
```

The handler exposes its Medicus instance as `handler.medicus`. Call `handler.medicus.stopBackgroundCheck()` on shutdown if you enable `backgroundCheckInterval`, and leave it unset on serverless and edge deployments.

## Query Parameters

* `?debug` - Include debug information
* `?last` - Return cached result
* `?simulate=unhealthy|degraded|healthy` - Simulate status

Healthy and degraded results return `200`, unhealthy results return `503`. Responses default to `Content-Type: application/json; charset=utf-8` and `Cache-Control: no-cache, no-store, must-revalidate`.

## Options

`createH3HealthCheckHandler` accepts every `Medicus` option except `context`, plus:

```ts
interface H3HealthCheckOptions {
  debug?: boolean; // Include debug info by default
  headers?: Record<string, string>; // Add or override response headers
}
```

For more details, visit the [H3](https://h3.dev/) and [Nitro](https://nitro.build/) documentation.
