# Nuxt Setup

> Setup Nuxt/Vue/TypeScript project. Use when user needs to install dependencies, prepare Nuxt, setup LSP, or fix TypeScript errors in a Nuxt/Vue project. Works in both main repo and worktrees.

- Skill: `martin-janci-claude-marketplace/nuxt-setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add martin-janci-claude-marketplace/nuxt-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/martin-janci-claude-marketplace/nuxt-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: martin-janci (https://skillmd.com/u/martin-janci-claude-marketplace)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/martin-janci-claude-marketplace/nuxt-setup

---


# Nuxt/Vue/TypeScript Project Setup

## Overview

Complete setup workflow for Nuxt 3 projects - from fresh clone to working LSP with full TypeScript support.

**Announce at start:** "I'm using the nuxt-setup skill to prepare this project."

## Quick Setup (TL;DR)

```bash
# 1. Detect package manager and install deps
yarn install  # or npm/pnpm based on lockfile

# 2. Prepare Nuxt (generates .nuxt types)
npx nuxt prepare

# 3. Verify TypeScript
npx vue-tsc --noEmit
```

## Package Manager Detection

Auto-detect from lockfile:

| File | Package Manager |
|------|-----------------|
| `yarn.lock` | yarn |
| `package-lock.json` | npm |
| `pnpm-lock.yaml` | pnpm |
| `bun.lockb` | bun |

```bash
# Detection logic
if [ -f yarn.lock ]; then
    PM="yarn"
elif [ -f pnpm-lock.yaml ]; then
    PM="pnpm"
elif [ -f bun.lockb ]; then
    PM="bun"
else
    PM="npm"
fi
```

## Full Setup Workflow

### 1. Install Dependencies

```bash
# Yarn (check .yarnrc.yml for version)
yarn install

# NPM
npm install

# PNPM
pnpm install

# Bun
bun install
```

**Common issues:**
- Yarn v2+ (Berry): Check `.yarnrc.yml` for `nodeLinker` setting
- Node version mismatch: Check `.nvmrc` or `engines` in `package.json`

### 2. Prepare Nuxt

```bash
npx nuxt prepare
```

This generates:
- `.nuxt/` directory
- `.nuxt/tsconfig.json` - TypeScript paths
- `.nuxt/types/` - Auto-imports, components, composables types

**Must run after:**
- Fresh clone
- Adding new auto-imported composables
- Changing `nuxt.config.ts`

### 3. Verify TypeScript

```bash
# Full type check
npx vue-tsc --noEmit

# Quick check specific file
npx vue-tsc --noEmit path/to/file.vue
```

### 4. LSP Setup

#### VS Code (Volar)

Required extensions:
- Vue - Official (`Vue.volar`)

Settings (`.vscode/settings.json`):
```json
{
  "typescript.tsdk": "node_modules/typescript/lib",
  "vue.server.hybridMode": true
}
```

#### Neovim (vue-language-server)

Mason install:
```vim
:MasonInstall vue-language-server typescript-language-server
```

LSP config:
```lua
require('lspconfig').volar.setup({
  filetypes = { 'vue', 'typescript', 'javascript' },
  init_options = {
    vue = {
      hybridMode = true,
    },
  },
})
```

#### Claude Code (bash-language-server + vue-tsc)

Verify setup:
```bash
# Check if types resolve
npx vue-tsc --noEmit 2>&1 | head -20
```

## Troubleshooting TypeScript Errors

### "Cannot find module" for auto-imports

```bash
# Regenerate types
rm -rf .nuxt
npx nuxt prepare
```

### "Cannot find module '#imports'"

The `#imports` alias is generated by Nuxt. Fix:
```bash
npx nuxt prepare
```

### Component type errors after adding new component

```bash
# Regenerate component types
npx nuxt prepare
```

### Path aliases not resolving (@/, ~/. #/)

Check `tsconfig.json` extends `.nuxt/tsconfig.json`:
```json
{
  "extends": "./.nuxt/tsconfig.json"
}
```

### Type errors in node_modules

Add to `tsconfig.json`:
```json
{
  "compilerOptions": {
    "skipLibCheck": true
  }
}
```

### Volar + TypeScript version mismatch

```bash
# Use workspace TypeScript
# VS Code: Cmd+Shift+P → "TypeScript: Select TypeScript Version" → "Use Workspace Version"
```

## Worktree Integration

When setting up a worktree:

```bash
# 1. After worktree creation, cd into it
cd .worktrees/<branch-name>

# 2. Install dependencies (node_modules not shared)
yarn install

# 3. Prepare Nuxt (types not shared)
npx nuxt prepare

# 4. Verify
npx vue-tsc --noEmit
```

**Note:** Each worktree needs its own `node_modules` and `.nuxt` directory.

## Environment Setup

### .env files

```bash
# Check required env vars
cat .env.example

# Copy and fill
cp .env.example .env
```

### Runtime config

Nuxt uses `runtimeConfig` in `nuxt.config.ts`. Check for required env vars:
```bash
grep -A20 "runtimeConfig" nuxt.config.ts
```

## Build Verification

```bash
# Development server
npx nuxt dev

# Production build
npx nuxt build

# Preview production
npx nuxt preview
```

## Common Project Files

| File | Purpose |
|------|---------|
| `nuxt.config.ts` | Nuxt configuration |
| `tsconfig.json` | TypeScript config (extends .nuxt/tsconfig.json) |
| `.nuxt/` | Generated types and build artifacts |
| `app.vue` | Root component |
| `pages/` | File-based routing |
| `components/` | Auto-imported components |
| `composables/` | Auto-imported composables |
| `server/` | Nitro server routes |

## Quick Reference

| Issue | Solution |
|-------|----------|
| Missing types | `npx nuxt prepare` |
| Module not found | `yarn install && npx nuxt prepare` |
| LSP not working | Restart LSP, check tsconfig extends .nuxt |
| Auto-imports broken | `rm -rf .nuxt && npx nuxt prepare` |
| Wrong TS version | Select workspace TypeScript in editor |
| Worktree setup | Install deps + nuxt prepare in worktree |

## Red Flags

**Never:**
- Skip `nuxt prepare` after clone
- Share `node_modules` between worktrees (symlinks break)
- Ignore `.nuxt/tsconfig.json` in project tsconfig

**Always:**
- Run `nuxt prepare` after config changes
- Use workspace TypeScript version
- Check env vars before running