Upgrading

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.

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.

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. The server.fastify option no longer accepts logger; Sonamu configures the logger through loggerInstance.

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.
`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:

pnpm-workspace.yaml

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:

web/tsconfig.node.json

{
  "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.

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

0.13.0

Fastify 5

Peer dependency changes

Projects generated with create-sonamu

​0.13.0

​Fastify 5

​Peer dependency changes

​Projects generated with create-sonamu

0.13.0

Fastify 5

Peer dependency changes

Projects generated with create-sonamu