Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

shadcn/ui setup fails in a Vite React project using Tailwind v4

Errorshadcn init cannot resolve the @/ import alias

Short answer

shadcn init needs three things in a Vite project: Tailwind v4 installed with the @tailwindcss/vite plugin and a single @import "tailwindcss" line in your CSS, the @/* path alias in both tsconfig.json and tsconfig.app.json, and the same alias in vite.config.ts, with @types/node installed so path resolves.

  • Applies to Vite, Tailwind CSS 4, shadcn CLI latest, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check that the three places the official Vite guide edits exist: tsconfig files, vite.config and the CSS entry.

    grep -n "paths" tsconfig.json tsconfig.app.json
    grep -n "tailwindcss\|alias" vite.config.ts
    head -3 src/index.css
  2. 2Match what you see, then jump to its fix

    1. 1shadcn init reports it cannot resolve the aliasThe @/* alias is missing from tsconfig.jsonFix
    2. 2Editor underlines the @/ imports even though the build worksThe alias is missing from tsconfig.app.jsonFix
    3. 3Build fails to resolve @/ imports, or path and __dirname are unknown to TypeScriptvite.config.ts has no alias, or Node types are missingFix
    4. 4Classes do nothing; the CSS still uses v3 directives or a PostCSS setupTailwind v4 is not wired the v4 wayFix

What does the error look like?

  • shadcn init cannot resolve the @/ import alias
  • Imports from @/components/ui do not resolve in the editor or the build
  • Tailwind classes have no effect after shadcn add

Cause 1 of 4

The @/* alias is missing from tsconfig.json

1Check

The shadcn Vite guide adds baseUrl and paths to compilerOptions in tsconfig.json.

grep -n "paths\|baseUrl" tsconfig.json

2Fix

Add the alias to the root tsconfig.json.

{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] }
  }
}

3Verify

Run the init again.

npx shadcn@latest init

Confirmed by ui.shadcn.com

Did this fix it?

Cause 2 of 4

The alias is missing from tsconfig.app.json

1Check

The guide also adds the same alias to tsconfig.app.json so the editor can resolve imports.

grep -n "paths" tsconfig.app.json

2Fix

Add baseUrl and paths to the compilerOptions of tsconfig.app.json.

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

3Verify

Restart the TypeScript server and open a file that imports from @/.

npx tsc -p tsconfig.app.json --noEmit

Confirmed by ui.shadcn.com

Did this fix it?

Cause 3 of 4

vite.config.ts has no alias, or Node types are missing

1Check

The guide installs @types/node so Vite can resolve the alias, and sets resolve.alias in vite.config.ts.

grep -n "@types/node" package.json

2Fix

Install the types and register the alias and the Tailwind plugin.

npm install -D @types/node

// vite.config.ts
import path from "path"
import tailwindcss from "@tailwindcss/vite"
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: { alias: { "@": path.resolve(__dirname, "./src") } },
})

3Verify

Build the project.

npm run build

Confirmed by ui.shadcn.com

Did this fix it?

Cause 4 of 4

Tailwind v4 is not wired the v4 way

1Check

In the guide, Tailwind is installed with the @tailwindcss/vite plugin and src/index.css contains one line, @import "tailwindcss".

cat src/index.css | head -5

2Fix

Install the plugin and replace the CSS contents with the single import.

npm install tailwindcss @tailwindcss/vite

/* src/index.css */
@import "tailwindcss";

3Verify

Add a Tailwind class to a component and check it is applied.

npm run dev

Confirmed by ui.shadcn.com

Did this fix it?

How do I stop it coming back?

  • Follow the shadcn Vite guide in order: Tailwind, CSS, both tsconfig files, vite.config, then init.
  • Run init only on a project that already builds.
  • Keep one alias definition in all three places.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.