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