shadcn/ui No import alias found 오류 해결: tsconfig 설정

1. 오류 원인과 빠른 진단

명령 또는 진단 메시지 — 자신의 실행 환경에 맞는 구간을 선택하세요.

No import alias found in your tsconfig.json file.
Visit https://ui.shadcn.com/docs/installation to learn how to set an import alias.

이 메시지는 Tailwind CSS가 동작하지 않는 오류와 다릅니다. shadcn/ui CLI는 components.json을 보고 파일을 생성하지만, TypeScript와 번들러는 tsconfig.json, jsconfig.json, vite.config.ts를 기준으로 import 경로를 해석합니다. 세 설정이 서로 다른 폴더를 가리키면 파일은 만들어져도 @/components/ui/button을 찾지 못합니다.

증상	먼저 확인할 곳	대표 원인
init 단계에서 alias 오류	tsconfig.json 또는 jsconfig.json	paths가 없거나 CLI 실행 위치가 다름
컴포넌트 생성 후 import 오류	components.json과 실제 폴더	@가 루트와 src 중 다른 곳을 가리킴
에디터는 되지만 Vite 실행 실패	vite.config.ts	TypeScript paths만 있고 Vite alias가 없음
모노레포에서만 실패	각 workspace의 설정 파일	루트가 아닌 앱 패키지에서 alias를 찾지 못함

2. components.json과 실제 폴더를 맞춥니다

components.json의 aliases는 shadcn/ui CLI가 생성 파일을 어디에 두고 어떤 import를 만들지 결정합니다. src/components/ui와 src/lib/utils.ts를 쓰는 프로젝트라면 다음처럼 맞춥니다.

부분 예제 — 앞뒤 설명에 해당하는 코드만 적용하세요. 다른 예제와 합친 전체 프로젝트가 아닙니다.

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "aliases": {
    "components": "@/components",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks",
    "utils": "@/lib/utils"
  }
}

중요한 점은 components.json만 고쳐서는 해결되지 않는다는 것입니다. 이 파일은 CLI의 생성 기준이고, @/*를 실제 경로로 바꾸는 일은 TypeScript와 번들러 설정이 담당합니다. src 폴더가 없다면 @/* → ./*를 사용하고, 있다면 @/* → ./src/*를 사용합니다.

3. Next.js에서 tsconfig paths를 맞춥니다

Next.js 프로젝트가 src 폴더를 사용한다면 루트 tsconfig.json에 다음 alias를 둡니다. 기존 compilerOptions를 지우지 말고 baseUrl과 paths만 합칩니다.

부분 예제 — 앞뒤 설명에 해당하는 코드만 적용하세요. 다른 예제와 합친 전체 프로젝트가 아닙니다.

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

src 없이 루트에 app, components, lib를 두었다면 배열 값을 ./*로 바꿉니다. 설정 후 @/components/ui/button이 실제로 src/components/ui/button.tsx 또는 components/ui/button.tsx에 도달하는지 폴더 구조를 직접 대조합니다.

4. Vite에서는 TypeScript와 번들러를 함께 설정합니다

Vite의 React·TypeScript 템플릿은 설정이 tsconfig.json과 tsconfig.app.json으로 나뉠 수 있습니다. shadcn/ui 공식 Vite 가이드는 두 파일에 같은 @/* → ./src/*를 두고, vite.config.ts에도 실제 alias를 등록하도록 안내합니다.

부분 예제 — 앞뒤 설명에 해당하는 코드만 적용하세요. 다른 예제와 합친 전체 프로젝트가 아닙니다.

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

부분 예제 — 앞뒤 설명에 해당하는 코드만 적용하세요. 다른 예제와 합친 전체 프로젝트가 아닙니다.

import path from "node:path";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

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

path 타입 오류가 나면 pnpm add -D @types/node로 Node 타입을 추가합니다. 이미 다른 alias 방식이나 플러그인을 사용 중이라면 새 방식을 겹쳐 넣지 말고 기존 설정에서 @의 대상만 확인합니다.

5. 모노레포와 package imports 예외

모노레포에서는 루트가 아니라 실제로 shadcn CLI를 실행하는 앱 workspace의 components.json과 TypeScript 설정을 확인합니다. 예를 들어 apps/web에 설치한다면 해당 디렉터리에서 실행하거나 -c apps/web를 지정합니다.

명령 또는 진단 메시지 — 자신의 실행 환경에 맞는 구간을 선택하세요.

pnpm dlx shadcn@latest add button -c apps/web

최신 shadcn CLI는 TypeScript paths 대신 package.json#imports의 #components/* 같은 별칭도 지원합니다. 다만 두 방식을 동시에 섞으면 진단이 어려워집니다. 기존 프로젝트가 @/*를 사용한다면 먼저 그 설정을 일관되게 맞추고, 마이그레이션이 필요할 때만 package imports를 검토합니다.

6. 수정 후 검증 순서

1. components.json의 ui와 utils가 실제 폴더를 가리키는지 확인합니다.
2. tsconfig.json 또는 jsconfig.json의 @/* 대상이 루트인지 src인지 확인합니다.
3. Vite라면 tsconfig.app.json과 vite.config.ts도 같은 기준으로 맞춥니다.
4. 모노레포라면 CLI 실행 위치와 -c 옵션을 확인합니다.
5. 작은 컴포넌트 하나를 추가한 뒤 타입 검사와 개발 서버를 실행합니다.

명령 또는 진단 메시지 — 자신의 실행 환경에 맞는 구간을 선택하세요.

pnpm dlx shadcn@latest add button
# Next.js 등 단일 tsconfig 프로젝트
pnpm exec tsc --noEmit
# Vite처럼 tsconfig references로 앱 설정을 나눈 프로젝트는 대신 실행
pnpm exec tsc -b
pnpm run dev

import 경로를 임시 상대 경로로 바꿔 오류를 숨기면 다음 컴포넌트 생성 때 같은 문제가 반복됩니다. CLI가 만든 @/components/ui/button import, 에디터 자동완성, TypeScript 검사, 실제 개발 서버가 모두 통과해야 해결된 것입니다.

공식 기준은 shadcn/ui components.json, shadcn/ui Vite 설치, shadcn/ui 모노레포 문서에서 확인할 수 있습니다. 관련 개념이 헷갈리면 Radix UI와 shadcn/ui 차이도 함께 확인합니다.