# Migration Guide: 11.21.x → 11.22.0

## Overview

| Category | Details |
|----------|---------|
| **Breaking Changes** | None |
| **New Features** | `ICoreModuleOverrides` — dedicated parameter for customizing core module components; npm package now includes `CLAUDE.md`, `.claude/rules/`, `docs/`, and `migration-guides/` for AI-assisted development |
| **Bugfixes** | Prevents duplicate controller registration when extending ErrorCodeModule |
| **Migration Effort** | ~5 minutes (optional, backward compatible) |

---

## Quick Migration (No Breaking Changes)

```bash
# Update package
pnpm add @lenne.tech/nest-server@11.22.0

# Verify build
pnpm run build

# Run tests
pnpm test
```

No code changes required. All existing patterns continue to work.

---

## What's New in 11.22.0

### 1. Module Override Parameter (`ICoreModuleOverrides`)

`CoreModule.forRoot()` now accepts an optional second parameter for replacing default controllers,
resolvers, or services of auto-registered core modules.

This solves the duplicate controller registration problem that occurred when projects called
`ErrorCodeModule.forRoot()` or `CoreBetterAuthModule.forRoot()` separately alongside CoreModule's
auto-registration.

**Before (caused duplicate routes):**

```typescript
@Module({
  imports: [
    CoreModule.forRoot(envConfig),
    // ❌ This caused duplicate controller registration because CoreModule
    //    already called ErrorCodeModule.forRoot() internally
    ErrorCodeModule.forRoot({
      controller: ErrorCodeController,
      service: ErrorCodeService,
    }),
  ],
})
export class ServerModule {}
```

**After (single registration, clean):**

```typescript
@Module({
  imports: [
    CoreModule.forRoot(envConfig, {
      errorCode: {
        controller: ErrorCodeController,
        service: ErrorCodeService,
      },
    }),
  ],
})
export class ServerModule {}
```

### Available Override Fields

| Module | Fields | Description |
|--------|--------|-------------|
| `errorCode` | `controller`, `service` | Custom error code endpoint and/or service |
| `betterAuth` | `controller`, `resolver` | Custom IAM REST controller and/or GraphQL resolver |

### Legacy Mode (3-parameter signature)

```typescript
CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig, {
  errorCode: {
    controller: ErrorCodeController,
    service: ErrorCodeService,
  },
  betterAuth: {
    resolver: BetterAuthResolver,
  },
})
```

### 2. Framework Documentation in npm Package

The npm package now includes `CLAUDE.md`, `.claude/rules/`, `docs/`, and `migration-guides/`.
This enables AI-assisted development tools (like Claude Code) to read the framework's
architecture documentation, configuration interfaces, and integration checklists directly
from `node_modules/@lenne.tech/nest-server/`.

**For AI-assisted development:** Add this to your project's `CLAUDE.md`:

```markdown
## Framework: @lenne.tech/nest-server
When working with framework features, read source and docs from:
node_modules/@lenne.tech/nest-server/CLAUDE.md
node_modules/@lenne.tech/nest-server/src/core/common/interfaces/server-options.interface.ts
node_modules/@lenne.tech/nest-server/src/core/modules/*/INTEGRATION-CHECKLIST.md
```

---

## Recommended Migration

While not required, migrating to the overrides pattern is recommended to prevent potential
duplicate controller registration issues.

### Step 1: Move ErrorCodeModule customization to overrides

If your project has a separate `ErrorCodeModule.forRoot()` call:

**Before:**
```typescript
imports: [
  CoreModule.forRoot(envConfig),
  ErrorCodeModule.forRoot({
    controller: ErrorCodeController,
    service: ErrorCodeService,
  }),
]
```

**After:**
```typescript
imports: [
  CoreModule.forRoot(envConfig, {
    errorCode: {
      controller: ErrorCodeController,
      service: ErrorCodeService,
    },
  }),
  // Remove the separate ErrorCodeModule.forRoot() call
]
```

### Step 2: Move BetterAuth customization to overrides (optional)

If your project uses `betterAuth.controller` or `betterAuth.resolver` in config:

**Before:**
```typescript
// config.env.ts
betterAuth: {
  controller: BetterAuthController,
  resolver: BetterAuthResolver,
}
```

**After:**
```typescript
// config.env.ts — remove controller/resolver from betterAuth config
betterAuth: { /* ... other config ... */ }

// server.module.ts
CoreModule.forRoot(envConfig, {
  betterAuth: {
    controller: BetterAuthController,
    resolver: BetterAuthResolver,
  },
})
```

Both approaches work — the overrides parameter takes precedence. The config fields remain
for backward compatibility.

### Step 3: Acknowledge deprecation warnings (no action required)

The `betterAuth.controller` and `betterAuth.resolver` fields in the config interface are now
marked as `@deprecated`. TypeScript will show strikethrough/warnings when these fields are used.

**No action required** — the fields still work. But when you have time, move them to the
`overrides` parameter (Step 2 above) to silence the warnings. This keeps class references
(code) separate from environment configuration (strings/numbers).

---

## Deprecations

| Field | Deprecated Since | Replacement | Removal |
|-------|-----------------|-------------|---------|
| `betterAuth.controller` | 11.22.0 | `CoreModule.forRoot(config, { betterAuth: { controller } })` | Not planned (backward compatible) |
| `betterAuth.resolver` | 11.22.0 | `CoreModule.forRoot(config, { betterAuth: { resolver } })` | Not planned (backward compatible) |

---

## Compatibility Notes

| Pattern | Status |
|---------|--------|
| `CoreModule.forRoot(envConfig)` without overrides | ✅ Works unchanged |
| `betterAuth.controller`/`resolver` in config | ✅ Works, overrides take precedence |
| `errorCode.autoRegister: false` + separate import | ✅ Works unchanged |
| `betterAuth.autoRegister: false` + separate import | ✅ Works unchanged |
| Separate `ErrorCodeModule.forRoot()` alongside CoreModule | ⚠️ Still works but causes duplicate controllers — use overrides instead. If your project already had this pattern, the duplicate registration still occurs but is harmless at runtime (NestJS deduplicates providers). The recommended migration is to use the overrides parameter. |

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Duplicate route handlers after update | Move `ErrorCodeModule.forRoot()` to `CoreModule.forRoot()` overrides parameter |
| TypeScript error on overrides parameter | Ensure `@lenne.tech/nest-server@11.22.0` is installed |
| Custom ErrorCode controller not registered | Check that `errorCode.autoRegister` is not set to `false` when using overrides |

---

## Module Documentation

- [ErrorCode INTEGRATION-CHECKLIST](../src/core/modules/error-code/INTEGRATION-CHECKLIST.md)
- [BetterAuth CUSTOMIZATION](../src/core/modules/better-auth/CUSTOMIZATION.md)
- [Configurable Features](../.claude/rules/configurable-features.md)
