[Next.js] shadcn 적용 방법(CRA를 이용한 React.js 또는 Next.js에 적용, vite를 이용한 React.js에 적용)

React.js 프로젝트에 shadcn을 적용하고자 하였다.  공식 페이지(https://ui.shadcn.com/docs/cli)에 있는 아래 명령어를 입력하였으나 정상적으로 설치되지 않았다.

npx shadcn@latest init

다른 여러 방법으로도 시도해 봤지만 결국 적용하지 못했다. 설치 실패 메시지 중 프레임워크를 찾을 수 없다는 내용이 반복되어서 결국 Next.js 프로젝트에 적용해 보게 되었고 너무도 자연스럽게 진행됨을 경험했다.

이 글을 쓰고 있는 시점에서 shadcn은 React.js 프로젝트보다는 Next.js 프로젝트(버전 15.0.3)에 적용하는 것이 정신건강에 이롭다고 정리해 본다.

1. Next.js 프로젝트에 shadcn 적용

Next.js 프로젝트에 shadcn 적용은 아래 공식 문서를 그대로 따라하면 쉽게 적용된다.

공식 문서: https://ui.shadcn.com/docs/installation/next

---

2024-11-17 추가

2. CRA를 이용한 React.js 프로젝트에  shadcn 적용

CRA를 이용한 React.js 프로젝트에  shadcn 적용을 재시도하였다.

1. shadcn에서 '@'경로 별칭을 사용하고 있어서 craco 모듈을 함께 사용하는 것이 속 편하다.

npm install @craco/craco

 

2. 기본적으로 CRA를 이용해 React.js 프로젝트를 생성할 때 Typescript를 적용해야 한다.

npx create-react-app . --template typescript

공식 문서 : https://create-react-app.dev/docs/adding-typescript/

 

3. shadcn 공식 문서의 설치 방법 중 manual 방식을 적용한다.

공식 문서 :  https://ui.shadcn.com/docs/installation/manual

공식 문서 내의 철차 중 1번 Add Tailwind CSS는 기본적으로 설치해야 한다.

2번의 Add dependencies도 반드시 진행하고,

3번 Configure path aliases에 해당하는 tsconfig.json에 컴파일러 옵션을 추가한다. src 폴더를 @로 사용할 수 있게 설정하였다. 아래는 전체 코드이다.

{
  "compilerOptions": {
    // 기존 속성 아래에 추가할 코드, @ 경로를 사용하는 속성이다.
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src", "src/lib"]
}

4번 Configure tailwind.config.js는 그대로 복붙 했다. 다만 content 속성은 "./src/**/*. {html, js, tsx}"를 적용했다.

/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: ["class"],
  content: ["./src/**/*.{html,js,tsx}"], // 여기 수정
  // 생략
  },
  plugins: [require("tailwindcss-animate")],
}

5번 Configure styles에 globals.css가 예제로 제시되고 있다. 나는 index.css 파일로 적용했다. CRA를 통해 프로젝트를 생성하면 index.tsx에 적용된 css가 index.css라서 그렇게 했다.

6번 Add a cn helper의 lib/utils.ts는 src 폴더 내에 생성했다.

7번 Create a components.json file의 components.json은 npx를 이용해 필요한 shadcn 컴포넌트를 설치하기 위해 반드시 존재해야 한다. "aliases" 속성에서 @는 src 폴더를 의미한다. 이에 대한 설정은 3번에서 진행했다.

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "src/index.css",
    "baseColor": "zinc",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

 

4. craco.config.js 파일을 생성한다.

const path = require('path');

module.exports = {
  webpack: {
    alias: {
      '@': path.resolve(__dirname, 'src')
    }
  }
}

 

5. package.json의 scripts를 수정한다.

{
  "scripts": {
    "start": "craco start",
    "build": "craco build",
    "test": "craco test"
  }
}

---

2024-12-18 추가

3. Vite를 이용한 React.js 프로젝트에 shadcn 적용

React.js에서 shadcn을 사용할 때는 Vite를 이용하는 것이 궁합이 잘 맞았다. 또한 shadcn은 Typescript 사용을 권장한다.

Vite를 이용한 Typescript 프로젝트 생성은 다음과 같다.

1. 프로젝트 생성

npm create vite@latest <프로젝트명> -- --template react-ts

 

2. tailwind, shadcn 적용

tailwind와 shadcn 적용은 shadcn 공식 문서를 참조하면 된다.

공식 문서: https://ui.shadcn.com/docs/installation/vite

위 공식 문서의 2번부터 끝까지 진행하면 된다.

2번 "tailwind.config.js" 설정에서 기존 코드는 "export default"로 시작하는데 공식 문서에는 [그림 1]과 같이 "module.exports"로 시작한다. 공식 문서의 코드 그대로 복붙해서 "module.exports"를 사용하면 된다.

[그림 1] 공식 문서 2번 tailwind.config.js 내보내기 방식 module.exports를 사용하면 된다.

 

3번 "tsconfig.json"과 tsconfig.app.json" 설정은 경로 별칭(alias) 관련 설정인데, src를 @로 사용하게 하는 설정이다. shadcn은 컴포넌트 설치 시 import 경로가 "@/lib/utils"와 같이 별칭을 사용하므로 이 설정을 반드시 잘해주어야 한다. 두 파일 중 하나라도 설정을 누락하면 컴파일 에러가 발생하므로 주의하자!