> ## 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.

# 업그레이드 안내

> Sonamu 버전을 올릴 때 필요한 변경 사항

## 0.13.0

### Fastify 5

Sonamu 0.13부터 Fastify 5와 그에 맞는 `@fastify/*` 플러그인 메이저 버전을 사용합니다. Fastify와
플러그인은 `sonamu`의 의존성이므로 `sonamu`를 올리고 `pnpm install`을 다시 실행하면 함께
갱신됩니다. 프로젝트가 `fastify`를 직접 의존성으로 선언했다면 `^5`로 맞추거나 제거하세요.

`@api`, `@websocket`, `@stream`, 인증, 파일 업로드 등 Sonamu가 제공하는 기능은 코드를 바꾸지
않아도 그대로 동작합니다. 다음 세 곳을 직접 사용했다면 확인이 필요합니다.

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

`@fastify/websocket` 11부터 두 번째 인자가 `{ socket }` 래퍼가 아닌 `ws.WebSocket`
인스턴스입니다. `connection.socket`을 `socket`으로 바꾸세요.

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

Fastify 4 전용 API(`request.routerPath`, `reply.context`, `reply.getResponseTime()`,
`reply.redirect(code, url)` 인자 순서 등)는 제거되거나 바뀌었습니다. Fastify 5
[마이그레이션 가이드](https://fastify.dev/docs/latest/Guides/Migration-Guide-V5/)를 참고하세요.
`server.fastify` 옵션에는 더 이상 `logger`를 넣을 수 없습니다. Sonamu가 `loggerInstance`로
로거를 설정합니다.

**3. request.hostname**

Fastify 5의 `request.hostname`에는 포트가 포함되지 않습니다. 포트가 필요하면 `request.port`
또는 `request.headers.host`를 사용하세요.

### peer 의존성 변경

0.13.0에서 범위가 바뀐 `sonamu`의 peer 의존성입니다. 프로젝트의 `pnpm-workspace.yaml` catalog를
같은 범위로 맞추세요.

| 패키지 | 이전 | 0.13.0 | 확인할 내용 |
| - | - | - | - |
| `better-auth`, `@better-auth/*` | `~1.6` | `~1.7` | `twoFactor.enable()` 응답이 `method`로 구분되는 유니온 타입으로 바뀌었습니다. `totpURI`, `backupCodes`는 `method === "totp"`일 때만 포함됩니다. |
| `zod` | `^4.3` | `^4.6` | better-auth 1.7이 요구하는 범위입니다. zod가 중복 설치되면 타입 오류가 발생하므로 catalog를 맞춘 뒤 `pnpm dedupe`를 실행하세요. |
| `ioredis` | `^5` | `^6` | Sonamu의 캐시·WebSocket 어댑터는 코드 변경 없이 동작합니다. ioredis를 직접 사용한다면 [ioredis 6 변경 사항](https://github.com/redis/ioredis/releases)을 확인하세요. |
| `knex` | `^3.2` | `^3.3` | 없음 |
| `pgvector` | `^0.2` | `^0.3` | 없음 |
| `voyageai` | `^0.0.8` | `^0.4` | 없음. Sonamu는 `VoyageAIClient.embed()`만 사용합니다. |
| `ai` | `^6` | `^7` | `streamText()` 결과 타입 `StreamTextResult`의 제네릭이 3개가 됐습니다. 직접 타입을 적었다면 `StreamTextResult<Tools, Context, Output>`으로 맞추세요. `toUIMessageStreamResponse()`의 `headers`는 `Headers` 인스턴스이므로 `Object.entries()`가 아닌 `headers.entries()`로 읽어야 합니다. |
| `@ai-sdk/anthropic`, `@ai-sdk/openai`, `@ai-sdk/provider` | `^3` | `^4` | 커스텀 provider는 V3 스펙(`ProviderV3`, `TranscriptionModelV3` 등)을 그대로 쓸 수 있습니다. |
| `@ai-sdk/provider-utils` | `^4` | `^5` | `ToolExecutionOptions`가 제네릭(`ToolExecutionOptions<Context>`)이 됐습니다. |

`fastify`는 위 Fastify 5 절을 참고하세요. 나머지 peer 의존성 범위는 그대로입니다.

템플릿 프로젝트의 개발 의존성도 함께 올랐습니다. `vitest` 5(`@vitest/coverage-v8` 포함)는
`clearMocks`가 기본으로 활성화되어, 앞선 테스트의 mock 호출 기록에 의존하던 테스트는 실패합니다.
`vite` 8.3, `dotenv` 18은 확인할 내용이 없습니다.

### create-sonamu로 생성한 프로젝트

생성된 프로젝트의 `pnpm-workspace.yaml`은 `seroval`을 `1.4.2`로 고정합니다. 이 버전에는
역직렬화 취약점이 있으므로 다음과 같이 바꾸세요.

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

`web/tsconfig.node.json`은 `vite.config.ts`를 검사하는데, Vite 플러그인의 타입 선언이 설치되지 않은
선택적 번들러(`webpack`, `rollup` 등)를 참조해 `sonamu build`의 web 타입 검사가 실패합니다.
`tsconfig.app.json`과 같이 `skipLibCheck`를 추가하세요.

```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"]
}
```

TanStack Router를 `1.170.45` 이상으로 올리는 것도 권장합니다. 1.170 generator는 `routeTree.gen.ts`를
새 형식으로 다시 쓰므로 첫 `sonamu dev` 실행 뒤 그 변경을 커밋하면 됩니다.

새로 생성하는 프로젝트에는 두 변경이 이미 적용되어 있습니다.


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