오늘은 프로젝트를 생성하고 필요한 패키지를 설치한 뒤 shadcn/ui를 프로젝트에 추가하는 작업까지를 기록해 보려고 한다. 내가 만드는 SNS 서비스에는 아래와 같은 패키지가 필요하다.
- 전역 상태 관리를 책임질 zustand
- zustand와 함께 사용하며, 데이터의 불변성을 책임질 immer
- 서버 데이터를 관리하기 위한 TanstackQuery
- 사용자가 작성할 폼의 유효성을 체크하기 위한 react-hook-form 그리고 zod
- 토스트 메시지를 띄우기 위한 sonner
- subase clinet를 연결하기 위한 supabase
- 그 외 코드 포맷팅을 위한 prettier, prettier-plugin-tailwindcss 등...
작업하다 추가적으로 더 필요한 것들은 그때 가서 설치하도록 하고, 자세한 설명은 각 라이브러리를 사용할 때가 되면 진행할 예정이다. 목록에 shadcn/ui가 포함되어 있지 않은 이유는 이것이 라이브러리가 아니기 때문이다.
프로젝트에 추가해서 사용한다면서 라이브러리가 아니라니, 그건 대체 무슨 말인지?
shadcn/ui는 tailwind css를 활용하여 작성한 컴포넌트의 모음이라고 보면 편하다. 맨 처음 공식 문서를 읽다 보면 아래와 같은 소개 문구를 바로 만나게 된다.
This is not a component library. It is how you build your component library.
즉, 라이브러리로서 존재하는 것이 아니라 사용자가 입맛에 맞게 컴포넌트를 구성할 수 있도록 도와준다는 것이다. 실제로 shadcn/ui에서 제공하고 있는 cli 명령어를 입력해 보면 package.json에 무언가 설치되는 것이 아니라 컴포넌트 파일 자체가 사용자가 설정한 폴더 내부(보통 src/components/ui)에 추가되는 것을 확인할 수 있다. 그렇다 보니 프로젝트에 추가한 이후로는 기본적으로 작성된 코드를 바탕으로 자유롭게 스타일을 변경하거나 원하는 variant를 추가하는 것도 가능하다.
보통 아무것도 없는 백지의 상태에서 input, button, comboBox 등의 컴포넌트를 구현하면 기능적 측면까지 전부 개발해야 하기 때문에 시간이 많이 소요되지만, 기본적인 기능(예를 들면 콤보박스의 드롭다운 메뉴에서 키보드 방향키를 통해 원하는 요소를 선택한다든지 하는)이 대부분 구현되어 있어 시간을 단축할 수 있는 점이 편하게 느껴졌다.
물론 사이드프로젝트를 혼자서 진행하는 입장에서는 그렇고, 실무 프로젝트나 디자인팀과의 협업을 진행할 때는 여러 가지 사항을 고려해봐야 할 것 같다. 어쨌든 나 혼자 사용하는 데에는 무리가 없을 것 같기도 하고 디자인이 세련되어 보여서 활용하기로 결정했다! 활용 방법은 일단 둘째 치고, 설정을 초기화하고 컴포넌트를 추가하는 것은 아주 친절하게 설명되어 있기 때문에 크게 어려울 것은 없다.
1. 초기화
먼저 shadcn/ui의 홈페이지(https://ui.shadcn.com/)에 접속한다. 문서 페이지로 접속하면 아래와 같은 화면을 만나볼 수 있는데, 나는 vite를 통해서 프로젝트를 생성했기 때문에 해당 버튼을 클릭하여 다음 단계로 진입했다.
먼저 프로젝트를 생성하고, npm install tailwindcss @tailwindcss/vite 명령어를 통해 tailwindcss를 설치한다. 먼저 설명했던 패키지 목록에서 tailwindcss가 빠져 있었던 것은 여기서 설치해야 하기 때문이다. shadcn/ui 자체가 tailwind를 기반으로 작성되었기 때문에 반드시 설치해야 정상적인 ui를 확인할 수가 있다. 또한, 컴포넌트를 수정할 때도 주로 활용하므로 기본적인 사용법은 알아야 편하게 작업이 가능하다.
이때 도움을 주는 것이 vscode 확장 프로그램인 Tailwind CSS IntelliSense
설치하면 사진처럼 자동 완성할 수 있는 옵션을 제공해 준다. 기본적인 작성법만 알면 편리하게 활용할 수 있기 때문에 추천!
아무튼 tailwind까지 설치했다면 index.css에 @import "tailwindcss"; 한 줄을 추가하면 첫 번째 단계는 완료했다. 그 다음으로는 tsconfig.json과 tsconfig.app.json 파일에 아래와 같은 코드를 추가한다. import 시 사용될 경로의 별칭을 정의하는 옵션이다.
참고로 tsconfig.json은 typescript 설정의 뼈대로서, 공통으로 쓰일 기본 옵션을 정의하며 tsconfig.app.json은 클라이언트(브라우저) 용 설정을 정의한다.
{
// ...
"compilerOptions": {
// ...
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"]
}
}
}우리는 vite 옵션을 선택했기 때문에, 우리가 추가한 경로 별칭 옵션을 vite에서도 인식할 수 있도록 vite.config.ts 파일을 아래와 같은 내용으로 업데이트해야 한다. 그리고 추가적으로 tailwindcss에 대한 코드도 함께 작성한다.
import path from "path"
import tailwindcss from "@tailwindcss/vite"
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"
// https://vite.dev/config/
export default defineConfig({
plugins: [react(), tailwindcss()],
resolve: {
alias: {
"@": path.resolve(__dirname, "./src"),
},
},
})여기까지 하면 설정은 끝! 터미널에서 초기화 명령어를 입력하면 shadcn/ui를 사용하기 위한 준비는 모두 끝났다고 볼 수 있다. 명령어를 실행하면 도중에 테마라든지 설정에 관련된 여러 질문을 하는데 차근차근 읽어보며 원하는 대로 설정을 해주면 된다.
npx shadcn@latest init초기화가 완료되면 index.css에 각종 변수들이 추가되고, 프로젝트 루트 경로에 components.json, src/lib 경로에 utils.ts, 그리고 src/components/ui 폴더가 생성된다. utils.ts 파일 내부에는 조건부 클래스 이름이나 변수를 활용해서 클래스 이름을 추가하고 그것들을 합칠 수 있는 함수가 작성되어 있다. (clsx를 사용함)
2. 컴포넌트 추가
이렇게 shadcn/ui를 사용할 준비를 마치면, 이제 ui를 구현하기 위해 필요한 컴포넌트를 추가하기만 하면 된다. 터미널에 npx shadcn@latest add button 명령어를 실행하면 아까 생성되었던 src/components/ui 폴더 하위에 Button.tsx라는 파일이 추가된다! 파일 내용을 확인해 보면 이미 대부분의 기능이나 기본적인 디자인이 적용되어 있는 버튼이 생성되어 있음을 확인할 수 있다. 이 버튼을 화면에 렌더링해보자. 이때 주의해야 할 점은, @radix-ui가 아니라 @/components/ui/~로 시작하는 경로에서 import 해야 한다는 것!
좌측의 컴포넌트는 화면 상 초록색 박스로 표시되어 있는 하단 네비게이션 바 부분을 구현한 것인데, 버튼을 렌더링할 뿐만 아니라 내부의 콘텐츠를 마음대로 적용할 수도 있고 무엇보다 가장 편리한 것은 className을 통해 어느 정도 원하는 수준으로 커스텀할 수 있다는 것이다!
물론 더 구체적으로 커스텀하기 위해서는 index.css 파일을 수정하거나 Button.tsx 파일을 직접 수정할 수도 있다. 파일을 직접 프로젝트에 추가하여 편리하게 사용자가 원하는 방식으로 커스텀할 수 있는 것이 정말 큰 장점 같다. 나는 index.css 파일을 크게 건드리지는 않았고, Pretendard 폰트를 적용하기 위해 아래에 보이는 코드 한 줄 정도만 추가해 주었다.
사진으로 확인할 수 있는 것처럼, 상단에 다양한 테마 색상들이 정의되어 있으니 원한다면 또는 필요하다면 얼마든 수정해서 사용하면 된다! 그리고 해당 파일의 가장 상단을 확인해 보면......
누가 봐도 다크 모드와 라이트 모드를 위해 생성된 것처럼 보이는 변수를 확인할 수가 있다. 이 내용은 다음 포스트에서 한 번 다뤄보려고 한다!
오늘은 tailwindcss를 내 프로젝트에 초기화하는 방법과 간단한 적용 예시까지 작성해보았다. 다음에는 조금 더 세세한 활용 예시와 다크/라이트 모드 적용 방법까지 기록해보자!
