nuxt-setup

name	nuxt-setup
description	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.

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)

# 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

# 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

# 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

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

# 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):

{
  "typescript.tsdk": "node_modules/typescript/lib",
  "vue.server.hybridMode": true
}

Neovim (vue-language-server)

Mason install:

:MasonInstall vue-language-server typescript-language-server

LSP config:

require('lspconfig').volar.setup({
  filetypes = { 'vue', 'typescript', 'javascript' },
  init_options = {
    vue = {
      hybridMode = true,
    },
  },
})

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

Verify setup:

# Check if types resolve
npx vue-tsc --noEmit 2>&1 | head -20

Troubleshooting TypeScript Errors

"Cannot find module" for auto-imports

# Regenerate types
rm -rf .nuxt
npx nuxt prepare

"Cannot find module '#imports'"

The #imports alias is generated by Nuxt. Fix:

npx nuxt prepare

Component type errors after adding new component

# Regenerate component types
npx nuxt prepare

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

Check tsconfig.json extends .nuxt/tsconfig.json:

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

Type errors in node_modules

Add to tsconfig.json:

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

Volar + TypeScript version mismatch

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

Worktree Integration

When setting up a worktree:

# 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

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

grep -A20 "runtimeConfig" nuxt.config.ts

Build Verification

# 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