strat-gameplay-webapp/frontend-sba/.claude/NUXT4_BREAKING_CHANGES.md

# Nuxt 4 Breaking Changes - Required Actions

**Date**: 2025-11-10
**Status**: Critical - Must Follow for All New Code

---

## 🚨 CRITICAL: Explicit Imports Required

Nuxt 4 removed auto-imports for Pinia stores and some composables. **You MUST explicitly import** these in your files.

### ❌ What No Longer Works (Nuxt 3 style):

```vue
<script setup lang="ts">
// This will cause "useAuthStore is not defined" error!
const authStore = useAuthStore()
</script>
```

### ✅ What You MUST Do (Nuxt 4 style):

```vue
<script setup lang="ts">
import { useAuthStore } from '~/store/auth'  // ← REQUIRED!

const authStore = useAuthStore()
</script>
```

---

## Required Explicit Imports

### 1. **All Pinia Stores**

```typescript
// In pages, components, middleware, plugins:
import { useAuthStore } from '~/store/auth'
import { useGameStore } from '~/store/game'
import { useUiStore } from '~/store/ui'
```

### 2. **Middleware Files**

**ALWAYS** import stores in middleware:

```typescript
// middleware/auth.ts
import { useAuthStore } from '~/store/auth'  // ← REQUIRED!

export default defineNuxtRouteMiddleware((to, from) => {
  const authStore = useAuthStore()
  // ... rest of middleware
})
```

### 3. **Pages**

```vue
<!-- pages/games/index.vue -->
<script setup lang="ts">
import { useAuthStore } from '~/store/auth'  // ← REQUIRED!
import { useGameStore } from '~/store/game'  // ← REQUIRED if using

const authStore = useAuthStore()
</script>
```

### 4. **Components**

```vue
<!-- components/GameCard.vue -->
<script setup lang="ts">
import { useGameStore } from '~/store/game'  // ← REQUIRED!

const gameStore = useGameStore()
</script>
```

---

## What Still Auto-Imports (No Explicit Import Needed)

These Nuxt/Vue composables still auto-import:

- ✅ `ref`, `computed`, `watch`, `reactive`, etc. (Vue)
- ✅ `useRoute`, `useRouter` (Vue Router)
- ✅ `useState`, `useFetch`, `useAsyncData` (Nuxt)
- ✅ `navigateTo`, `definePageMeta` (Nuxt)
- ✅ `onMounted`, `onUnmounted` (Vue lifecycle)

**BUT NOT:**
- ❌ Your custom stores (`useAuthStore`, `useGameStore`, etc.)
- ❌ Your custom composables in `composables/` folder (sometimes - test to verify)

---

## Quick Reference: When to Add Imports

| File Type | Needs Explicit Imports? | Example |
|-----------|------------------------|---------|
| `pages/*.vue` | ✅ YES | `import { useAuthStore } from '~/store/auth'` |
| `components/*.vue` | ✅ YES | `import { useGameStore } from '~/store/game'` |
| `middleware/*.ts` | ✅ YES | `import { useAuthStore } from '~/store/auth'` |
| `plugins/*.ts` | ✅ YES | `import { useAuthStore } from '~/store/auth'` |
| `store/*.ts` | ✅ YES (for other stores) | `import { useAuthStore } from './auth'` |
| `composables/*.ts` | ⚠️ MAYBE | Test - may need imports for stores |

---

## Common Errors and Fixes

### Error: "useAuthStore is not defined"

**Location**: Any `.vue` or `.ts` file
**Fix**: Add `import { useAuthStore } from '~/store/auth'` at top of `<script>` section

### Error: "useGameStore is not defined"

**Location**: Any `.vue` or `.ts` file
**Fix**: Add `import { useGameStore } from '~/store/game'` at top of `<script>` section

### Error: "useUiStore is not defined"

**Location**: Any `.vue` or `.ts` file
**Fix**: Add `import { useUiStore } from '~/store/ui'` at top of `<script>` section

---

## Standard Import Pattern for New Files

Use this template for all new `.vue` files:

```vue
<template>
  <!-- Your template -->
</template>

<script setup lang="ts">
// 1. Import stores (if needed)
import { useAuthStore } from '~/store/auth'
import { useGameStore } from '~/store/game'

// 2. Import types (if needed)
import type { GameState, Player } from '~/types'

// 3. Define page meta (if needed)
definePageMeta({
  middleware: ['auth'],
})

// 4. Initialize stores
const authStore = useAuthStore()
const gameStore = useGameStore()

// 5. Composables (these auto-import, no need to import)
const route = useRoute()
const router = useRouter()

// 6. Component logic
const someValue = ref('')
// ...
</script>
```

---

## Why This Changed

Nuxt 4 prioritizes **explicit over implicit** for better:
- Type safety
- Build performance
- Code clarity
- IDE support

The tradeoff is more boilerplate, but it prevents "magic" import bugs.

---

## Verification Checklist

Before committing new code:

- [ ] Check all `useAuthStore()` calls have import
- [ ] Check all `useGameStore()` calls have import
- [ ] Check all `useUiStore()` calls have import
- [ ] Check middleware files have store imports
- [ ] Run dev server - no "X is not defined" errors
- [ ] Test page navigation - no 500 errors

---

## Related Changes

This document relates to:
- **Nuxt 4 Directory Structure**: Added `srcDir: '.'` to `nuxt.config.ts` (see `.claude/PHASE_F1_NUXT_ISSUE.md`)
- **TypeScript in Dev**: Disabled `typeCheck: true` in dev mode for performance

---

## 🚨 CRITICAL: No `app/` Directory in Project Root

**Added**: 2025-12-03

In Nuxt 4, the `app/` directory is a **reserved special directory** that takes precedence over root-level files like `app.vue`.

### The Problem

If an `app/app.vue` file exists, Nuxt will use it instead of the root `app.vue`, even with `srcDir: '.'` configured. This can cause unexpected behavior like the default `NuxtWelcome` component rendering instead of your actual pages.

### What To Avoid

```
frontend-sba/
├── app/                    ← ❌ DO NOT CREATE THIS
│   └── app.vue             ← Will override root app.vue!
├── app.vue                 ← ✅ Your actual app entry point
├── pages/
│   └── index.vue
└── nuxt.config.ts
```

### If You See NuxtWelcome in Production

1. Check if `app/` directory exists: `ls -la app/`
2. If it contains `app.vue` with `<NuxtWelcome />`, delete the entire directory:
   ```bash
   rm -rf app/
   ```
3. Rebuild: `./start.sh rebuild prod`

### Why This Happens

Nuxt 4's initialization (`npx nuxi init`) creates an `app/app.vue` with the default welcome component. If you then set `srcDir: '.'` to use root-level directories, both files exist and `app/` takes priority.

---

**Always import your stores explicitly!**