docs(nuxt): add tsconfig alias section and set componentDir to app/components/ui (Nuxt 4)

[huangjunsen0406]

🔗 Linked issue

Refs: #1330, #1384

❓ Type of change

• 📖 Documentation (updates to the documentation, readme or JSdoc annotations)
• 🐞 Bug fix
• 👌 Enhancement
• ✨ New feature
• 🧹 Chore
• ⚠️ Breaking change

📚 Description

Explain
Nuxt 4 defaults to the app/ directory and commonly uses a root tsconfig.json with project references only.
The shadcn-vue CLI validates TS path aliases from tsconfig.json/jsconfig.json, so without explicit compilerOptions.paths, users can hit “No import alias found”.
Also, pointing componentDir at ./components/ui (Nuxt 3 style) can confuse Nuxt 4 users whose components live under app/components/ui.

What this PR changes

1. Add a tsconfig.json (aliases) section (before nuxt.config.ts) showing explicit compilerOptions.paths:
   • Keep @/* and ~/* mapped to project root.
   • Map @/components/* → ./app/components/* (Nuxt 4).
2. In Configure nuxt.config.ts, set
   shadcn.componentDir = './app/components/ui' for Nuxt 4.
3. Doc note about ordering: run the CLI before nuxi prepare (or mention mkdir -p app/components/ui) to avoid the “Component directory does not exist …/components/ui” warning.
4. Keep Nuxt 3 instructions intact.

Why
Ensures init/add pass alias validation and avoids confusing warnings for Nuxt 4 users.
Forward-compatible with ongoing work to auto-detect tsconfig for Nuxt (#1330, #1384).

Tested

• Fresh Nuxt 4 app:
  • npx shadcn-vue@latest init ✅
  • npx shadcn-vue@latest add button ✅
  • npx nuxi prepare → no warnings ✅

📸 Screenshots (if appropriate)

N/A (docs-only)

📝 Checklist

• I have linked an issue or discussion. (Refs: feat(cli): add tsconfig file detection based on the framework #1330, fix: support TypeScript project references in Nuxt 4 #1384)
• I have updated the documentation accordingly.

[huangjunsen0406]

Docs feedback (Nuxt installation) — based on https://www.shadcn-vue.com/docs/installation/nuxt.html

In a fresh Nuxt 4 + Tailwind v4 project, strictly following the page above, I hit a blocker during init:

pnpm dlx shadcn-vue@latest init
✔ Validating Tailwind CSS config. Found v4.
✖ Validating import alias.
No import alias found in your tsconfig.json file.

Root cause

• The CLI validates TypeScript path aliases from the root tsconfig.json/jsconfig.json (compilerOptions.paths).
• In Nuxt 4, the root tsconfig.json commonly contains only files: [] + project references, and the current stable CLI does not automatically merge aliases from .nuxt/tsconfig.*.json. Hence the No import alias found error.

Minimal fix (Nuxt 4 / app directory)

Add explicit aliases to the root tsconfig.json (plain JSON, no comments). After this, both init and add work:

{
  "references": [
    { "path": "./.nuxt/tsconfig.app.json" },
    { "path": "./.nuxt/tsconfig.server.json" },
    { "path": "./.nuxt/tsconfig.shared.json" },
    { "path": "./.nuxt/tsconfig.node.json" }
  ],
  "files": [],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"],
      "~/*": ["./*"],
      "@/components/*": ["./app/components/*"]
    }
  }
}

@sadeghbarati

[sadeghbarati]

Hi @huangjunsen0406 , the Nuxt team and the TypeScript team are against using baseUrl in tsconfig files

PR I created needs to be tested, the pkg.pr.new is there, and instructions are also explained there for using shadcn-vue in Nuxt 4 or 3

Please, if you have time, go test it and give us feedback so we can merge that PR sooner

[huangjunsen0406]

Hi @huangjunsen0406 , the Nuxt team and the TypeScript team are against using baseUrl in tsconfig files

PR I created needs to be tested, the pkg.pr.new is there, and instructions are also explained there for using shadcn-vue in Nuxt 4 or 3

Please, if you have time, go test it and give us feedback so we can merge that PR sooner

Hi @sadeghbarati — I’ve tested as requested. Here’s the report.

Tested on Nuxt 4 + Tailwind v4 (with @tailwindcss/vite), no baseUrl

• Nuxt: 4.x (compatibilityDate: 2025-07-15)
• Tailwind: v4 (via @tailwindcss/vite)
• Module: shadcn-nuxt
• CLI (preview): npm i https://pkg.pr.new/shadcn-vue@1330 → shadcn-vue init / shadcn-vue add button

Result

• Components installed under app/components/ui ✅
• Button renders with correct styles ✅
• No baseUrl in root tsconfig ✅

Docs suggestion

• For Nuxt 4, recommend shadcn.componentDir = './app/components/ui'.
• Remove baseUrl usage from docs per maintainer guidance.
• Keep aliases in components.json as "ui": "@/components/ui" so the CLI aligns with Nuxt 4’s app/ layout.

Refs: #1330 (pkg.pr.new CLI preview), #1384. ([GitHub]1)

{
  // https://nuxt.com/docs/guide/concepts/typescript
  "files": [],
  "references": [
    {
      "path": "./.nuxt/tsconfig.app.json"
    },
    {
      "path": "./.nuxt/tsconfig.server.json"
    },
    {
      "path": "./.nuxt/tsconfig.shared.json"
    },
    {
      "path": "./.nuxt/tsconfig.node.json"
    }
  ],
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"],
      "~/*": ["./*"],
      "@/components/*": ["./app/components/*"]
    }
  }
}

[sadeghbarati]

Let me create a StackBlitz for you

The aliases you add in root tsconfig.json is already defined in the .nuxt/tsconfig.app.json the new CLI detect Nuxt 4 and choose .nuxt/tsconfig.app.json as the default tsconfig for CLI

https://stackblitz.com/edit/github-wgwbnhs5

[huangjunsen0406]

Let me create a StackBlitz for you

The aliases you add in root tsconfig.json is already defined in the .nuxt/tsconfig.app.json the new CLI detect Nuxt 4 and choose .nuxt/tsconfig.app.json as the default tsconfig for CLI

https://stackblitz.com/edit/github-wgwbnhs5

Hi, sorry for the late response — I’ve been swamped recently.

I’m unable to get your sample project running. I also tried re-running:

pnpm dlx shadcn-vue@latest init

but still get “No import alias found in your tsconfig.json.”
In my testing, it only passes the preflight if I add aliases to the root tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"],
      "~/*": ["./*"]
    }
  }
}

Could you please try creating a fresh Nuxt 4 project and following the steps here to verify?
https://www.shadcn-vue.com/docs/installation/nuxt.html

If the latest CLI still requires aliases in the root tsconfig.json, it might be worth documenting or updating the CLI to read .nuxt/tsconfig.app.json by default for Nuxt 4. Thanks!

[sadeghbarati]

We are working on v4-docs, and we will open PR soon