/nuxt-setup

name: nuxt-v4:setup
description: Interactive wizard to set up a new Nuxt 4 project with database integration, UI framework, authentication, and deployment configuration. Use when user wants to create a new Nuxt project or scaffold a full-stack application.

Nuxt Setup Wizard

Overview

Interactive wizard for complete Nuxt 4 setup: create project, configure modules, add database integration, set up authentication, and configure deployment.

Prerequisites

Check before starting:

• Node.js 20+ or Bun installed
• Package manager available (bun, npm, or pnpm)
• Write access to target directory

Steps

Step 1: Gather Requirements

Use AskUserQuestion to collect setup preferences.

**Question 1: Project Type**

header: "Project Type"
question: "What type of application are you building?"
options:
  - label: "Full-Stack Web App (Recommended)"
    description: "SSR, API routes, database, authentication"
  - label: "Marketing Site"
    description: "Static pages, SEO optimized, fast loading"
  - label: "API Backend"
    description: "Server routes only, no frontend"
  - label: "SPA Dashboard"
    description: "Client-side only, no SSR"

**Store as**: `projectType`

**Question 2: UI Framework**

header: "UI Framework"
question: "Which UI framework would you like to use?"
options:
  - label: "Nuxt UI v4 (Recommended)"
    description: "100+ accessible components, Tailwind v4, Reka UI"
  - label: "Tailwind CSS only"
    description: "Utility-first CSS, no component library"
  - label: "shadcn-vue"
    description: "Copy-paste components with Radix Vue"
  - label: "None"
    description: "No UI framework, custom styling"

**Store as**: `uiFramework`

**Question 3: Features** (multiSelect: true)

header: "Features"
question: "Which features do you need?"
multiSelect: true
options:
  - label: "Authentication"
    description: "User login, sessions, protected routes"
  - label: "Database"
    description: "D1/PostgreSQL with Drizzle ORM"
  - label: "Content/Blog"
    description: "Nuxt Content for markdown-based content"
  - label: "Testing"
    description: "Vitest for unit and component tests"

**Store as**: `features` (array)

**Question 4: Database** (if "Database" selected)

header: "Database"
question: "Which database would you like to use?"
options:
  - label: "Cloudflare D1 (Recommended)"
    description: "SQLite at the edge, great for Cloudflare deployment"
  - label: "NuxtHub"
    description: "All-in-one Cloudflare integration (D1, KV, R2)"
  - label: "PostgreSQL"
    description: "Traditional SQL database"
  - label: "None"
    description: "No database, will configure manually"

**Store as**: `database`

**Question 5: Deployment Target**

header: "Deployment"
question: "Where will you deploy?"
options:
  - label: "Cloudflare Pages (Recommended)"
    description: "Global edge, automatic builds, great free tier"
  - label: "Cloudflare Workers"
    description: "Edge functions with more control"
  - label: "Vercel"
    description: "Great DX, serverless functions"
  - label: "Netlify"
    description: "Simple hosting, good for static sites"
  - label: "Node Server"
    description: "Traditional Node.js server"

**Store as**: `deployment`

**Question 6: Package Manager**

header: "Package Manager"
question: "Which package manager do you prefer?"
options:
  - label: "bun (Recommended)"
    description: "Fast, all-in-one runtime and package manager"
  - label: "pnpm"
    description: "Efficient disk space, fast installs"
  - label: "npm"
    description: "Standard Node.js package manager"

**Store as**: `packageManager`

---

Step 2: Create Project

**Ask for project name**:

header: "Project Name"
question: "What should your project be called?"

**Validation**: Lowercase alphanumeric + hyphens only **Store as**: `projectName`

**Execute**:

# Create Nuxt 4 project
bunx nuxi@latest init <projectName> --package-manager <packageManager>

# Navigate to project
cd <projectName>

**Verify**:

ls -la
# Should see: nuxt.config.ts, package.json, app/, etc.

**Error Handling**:

• If directory exists → Ask user if they want to overwrite or choose different name
• If nuxi fails → Check Node.js version, suggest updates

---

Step 3: Configure nuxt.config.ts

Build configuration based on user selections:

// nuxt.config.ts
export default defineNuxtConfig({
  // Enable Nuxt 4 features
  future: {
    compatibilityVersion: 4
  },

  // Development tools
  devtools: { enabled: true },

  // Modules (based on selections)
  modules: [
    // If uiFramework == "Nuxt UI v4"
    '@nuxt/ui',
    // If uiFramework == "Tailwind CSS only"
    '@nuxtjs/tailwindcss',
    // If features includes "Content/Blog"
    '@nuxt/content',
    // If features includes "Database" && database == "NuxtHub"
    '@nuxthub/core',
    // If features includes "Testing"
    '@nuxt/test-utils/module',
  ],

  // Nitro preset (based on deployment)
  nitro: {
    // If deployment == "Cloudflare Pages"
    preset: 'cloudflare-pages',
    // If deployment == "Cloudflare Workers"
    preset: 'cloudflare-module',
    // If deployment == "Vercel"
    preset: 'vercel',
    // If deployment == "Netlify"
    preset: 'netlify',
  },

  // NuxtHub config (if selected)
  // If database == "NuxtHub"
  hub: {
    database: true,
    kv: true,
    blob: true,
    cache: true
  },

  // Runtime config
  runtimeConfig: {
    // Server-only secrets
    apiSecret: process.env.API_SECRET,
    // Public config
    public: {
      appName: '<projectName>'
    }
  },

  // TypeScript
  typescript: {
    strict: true,
    typeCheck: true
  },

  // Route rules (based on projectType)
  routeRules: {
    // If projectType == "Marketing Site"
    '/': { prerender: true },
    '/about': { prerender: true },
    // If projectType == "SPA Dashboard"
    '/dashboard/**': { ssr: false },
  }
})

**Use Edit tool** to update nuxt.config.ts with generated configuration