> ## Documentation Index
> Fetch the complete documentation index at: https://sonamu.cartanova.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading

> Changes required when upgrading Sonamu

## 0.13.0

### Fastify 5

Starting with Sonamu 0.13, the framework runs on Fastify 5 and the matching major versions of
the `@fastify/*` plugins. Fastify and its plugins are dependencies of `sonamu`, so bumping
`sonamu` and re-running `pnpm install` upgrades them together. If your project declares
`fastify` directly, align it to `^5` or remove it.

Everything Sonamu provides (`@api`, `@websocket`, `@stream`, auth, file upload, and so on)
works without code changes. Review the three places below only if your project uses them
directly.

**1. server.plugins.ws.errorHandler**

From `@fastify/websocket` 11, the second argument is the `ws.WebSocket` instance instead
of a `{ socket }` wrapper. Replace `connection.socket` with `socket`.

**2. server.plugins.custom, lifecycle.onError**

Fastify 4-only APIs (`request.routerPath`, `reply.context`, `reply.getResponseTime()`,
the `reply.redirect(code, url)` argument order, and others) were removed or changed. See
the Fastify 5
[migration guide](https://fastify.dev/docs/latest/Guides/Migration-Guide-V5/). The
`server.fastify` option no longer accepts `logger`; Sonamu configures the logger through
`loggerInstance`.

**3. request.hostname**

In Fastify 5, `request.hostname` no longer includes the port. Use `request.port` or
`request.headers.host` when you need it.

### Peer dependency changes

These `sonamu` peer dependency ranges changed in 0.13.0. Align the catalog in your project’s
`pnpm-workspace.yaml` to the same ranges.

| Package | Before | 0.13.0 | What to check |
| - | - | - | - |
| `better-auth`, `@better-auth/*` | `~1.6` | `~1.7` | `twoFactor.enable()` now returns a union discriminated by `method`; `totpURI` and `backupCodes` exist only when `method === "totp"`. |
| `zod` | `^4.3` | `^4.6` | Required by better-auth 1.7. Two installed copies of zod cause type errors, so align the catalog, then run `pnpm dedupe`. |
| `ioredis` | `^5` | `^6` | Sonamu’s cache and WebSocket adapters work without code changes. If you use ioredis directly, see the [ioredis 6 release notes](https://github.com/redis/ioredis/releases). |
| `knex` | `^3.2` | `^3.3` | None |
| `pgvector` | `^0.2` | `^0.3` | None |
| `voyageai` | `^0.0.8` | `^0.4` | None. Sonamu only calls `VoyageAIClient.embed()`. |
| `ai` | `^6` | `^7` | `StreamTextResult`, the return type of `streamText()`, now takes three type arguments; if you spell it out, use `StreamTextResult<Tools, Context, Output>`. `toUIMessageStreamResponse().headers` is a `Headers` instance, so read it with `headers.entries()`, not `Object.entries()`. |
| `@ai-sdk/anthropic`, `@ai-sdk/openai`, `@ai-sdk/provider` | `^3` | `^4` | Custom providers written against the V3 specs (`ProviderV3`, `TranscriptionModelV3`, and so on) keep working. |
| `@ai-sdk/provider-utils` | `^4` | `^5` | `ToolExecutionOptions` is now generic: `ToolExecutionOptions<Context>`. |

`fastify` is covered in the Fastify 5 section above. All other peer ranges are unchanged.

The template project’s dev dependencies moved as well. `vitest` 5 (with `@vitest/coverage-v8`)
enables `clearMocks` by default, so tests that rely on mock call history from earlier tests
will fail. `vite` 8.3 and `dotenv` 18 need no attention.

### Projects generated with create-sonamu

A generated project’s `pnpm-workspace.yaml` pins `seroval` to `1.4.2`. That version has a
deserialization vulnerability, so change the override to:

```yaml pnpm-workspace.yaml theme={null}
overrides:
  seroval: ^1.6.11
  seroval-plugins: 1.5.6
```

`web/tsconfig.node.json` typechecks `vite.config.ts`, and the Vite plugins’ type declarations
reference optional bundlers that are not installed (`webpack`, `rollup`, and others), which makes
the web typecheck step of `sonamu build` fail. Add `skipLibCheck`, as `tsconfig.app.json` already does:

```json web/tsconfig.node.json theme={null}
{
  "compilerOptions": {
    "composite": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "include": ["vite.config.ts"]
}
```

Upgrading TanStack Router to `1.170.45` or later is also recommended. The 1.170 generator rewrites
`routeTree.gen.ts` in a new format; commit that change after the first `sonamu dev` run.

Newly generated projects already include both changes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.