React·Tailwind 호환성 확인

21st add는 공식 문서상 npx shadcn@latest add를 호출해 컴포넌트와 의존성을 프로젝트에 넣습니다. 따라서 21st 페이지에서 미리보기가 정상이어도 현재 프로젝트 설정과 자동으로 호환된다는 뜻은 아닙니다.

  • 파일 상단의 "use client"와 React 훅 사용 여부가 서버 컴포넌트 경계와 맞는지 확인합니다.
  • @/components, @/lib/utils 같은 경로 별칭이 프로젝트의 tsconfig와 일치하는지 봅니다.
  • 추가된 npm 패키지의 버전 범위가 현재 React 버전과 충돌하지 않는지 패키지 관리자 경고를 읽습니다.
  • 전역 CSS 변수와 Tailwind 유틸리티가 현재 설정에 존재하는지 확인합니다.
  • 아이콘, 애니메이션과 폰트 패키지가 실제 사용량에 비해 과도하지 않은지 빌드 결과를 비교합니다.
  • 브라우저 전용 API를 렌더링 중 바로 호출하지 않는지 확인해 SSR 오류를 막습니다.

공식 게시 가이드도 npm 의존성을 package.json에 선언하고 공용 헬퍼를 명시적으로 포함하도록 안내합니다. 설치된 파일이 내부 경로나 누락된 데모 헬퍼를 참조하면 해당 작성자의 예제 구조를 확인하되, 쓰지 않는 코드를 통째로 추가하기보다 필요한 함수만 프로젝트 규칙에 맞춰 옮깁니다.

웹에서 가장 쉽게 사용하기

  1. 21st.dev에서 필요한 UI 종류를 검색합니다.
  2. 미리보기와 모바일 동작을 확인합니다.
  3. 설치 명령, 코드와 필요한 패키지를 확인합니다.
  4. 새 브랜치에서 컴포넌트를 설치합니다.
  5. 프로젝트 색상과 접근성 규칙에 맞게 수정합니다.

개별 컴포넌트는 shadcn 호환 명령을 제공하는 경우가 많습니다.

npx shadcn@latest add https://21st.dev/r/사용자/컴포넌트

실제 주소는 선택한 컴포넌트 페이지의 설치 명령을 그대로 사용합니다.

검색과 CLI 설치 흐름을 설명하는 21st.dev 공식 도움말 화면

공식 CLI 설치

npm i -g @21st-dev/cli
21st login

전역 설치 없이 검색만 해보려면 다음처럼 실행합니다.

npx @21st-dev/cli search "pricing table"

이전 @21st-dev/registry나 @21st-dev/magic 대신 현재 공식 문서는 통합 CLI인 @21st-dev/cli 사용을 안내합니다.

CLI로 검색하고 설치하기

21st search "hero section" --type component --limit 5
21st search "dark dashboard" --type theme
21st search "saas starter" --type template --free
21st add 사용자/슬러그

search는 무료·유료 필터, 작성자, 색상과 항목 종류를 지원합니다. add는 shadcn 호환 레지스트리를 통해 코드와 의존성을 프로젝트에 설치합니다.

검색 결과의 코드를 바로 실행하기 전에 get과 --print로 내용을 확인할 수 있습니다.

21st search "pricing table" --type component --free --limit 5
21st get 검색결과_ID
21st add 사용자/슬러그 --print

--print는 실제 설치 대신 21st가 실행할 shadcn 명령을 출력합니다. 작성자, 레지스트리 URL과 대상 슬러그가 기대한 값인지 확인한 다음 --print를 빼고 설치합니다. 특히 AI가 검색 결과를 골랐다면 이름이 비슷한 다른 작성자의 컴포넌트를 선택하지 않았는지 이 단계를 건너뛰지 않는 편이 좋습니다.

가격표 하나를 시험하는 안전한 흐름

기존 작업과 섞이지 않도록 먼저 별도 브랜치를 만들고 작업 트리가 깨끗한지 확인합니다.

git switch -c try/21st-pricing
git status --short
21st search "responsive pricing table" --type component --free --limit 5
21st add 사용자/슬러그 --print
21st add 사용자/슬러그
git status --short

설치 후에는 바로 페이지 전체를 교체하지 말고 개발용 경로에서 컴포넌트만 렌더링합니다. 실제 요금제 이름처럼 긴 텍스트, 추천 배지 유무, 월간·연간 전환과 320px 화면을 넣어 미리보기와 다른 상태에서도 레이아웃이 유지되는지 확인합니다. 통과하면 프로젝트의 색상 토큰과 버튼 컴포넌트에 연결하고, 불필요한 데모 데이터와 임시 이미지를 제거합니다.

설치 후 반드시 확인할 것

  • 새 의존성이 과도하게 추가되지 않았는가
  • 컴포넌트가 프로젝트의 React와 Tailwind 버전에 맞는가
  • 키보드 조작과 포커스 표시가 작동하는가
  • 모바일에서 긴 텍스트와 버튼이 잘리지 않는가
  • 복사한 컴포넌트의 라이선스를 지켰는가
  • 기존 디자인 시스템과 색상·간격이 충돌하지 않는가

설치를 되돌리는 방법

21st 컴포넌트는 설치 뒤 프로젝트가 소유하는 일반 소스 파일이 되므로 모든 항목에 공통으로 적용되는 21st remove 명령은 기대하지 않는 편이 좋습니다. 설치 직전 상태와 git diff를 비교해 추가된 컴포넌트, 수정된 CSS와 package.json 변경을 한 묶음으로 확인합니다.

시험을 중단할 때는 새로 생긴 컴포넌트 파일을 제거하고, 다른 코드에서 사용하지 않는 직접 의존성만 패키지 관리자로 삭제합니다. 잠금 파일을 손으로 편집하지 말고 npm·pnpm·bun 중 프로젝트가 이미 쓰는 도구로 갱신합니다. 같은 브랜치에 다른 수정이 있다면 전체 작업 트리를 초기화하지 말고 설치 커밋이나 대상 파일만 골라 되돌립니다. 마지막으로 프로젝트 빌드와 기존 UI 테스트를 실행해 경로 별칭이나 CSS 변수가 남아 있지 않은지 확인합니다.

21st.dev는 무엇인가

21st.dev는 커뮤니티가 만든 React·Tailwind 컴포넌트, 테마와 웹사이트 템플릿을 찾고 설치할 수 있는 마켓플레이스입니다. 원하는 자료가 없으면 21st AI에서 설명을 입력해 여러 UI 시안을 생성하고 수정할 수도 있습니다.

21st.dev에서 React 컴포넌트와 템플릿을 탐색하는 공식 카탈로그 화면

21st AI와 MCP

21st AI는 프롬프트로 여러 디자인 초안을 만들고 선택한 안을 자연어로 수정하는 기능입니다. CLI와 MCP를 사용하면 편집기나 AI 에이전트 안에서 검색, 생성과 설치 흐름을 연결할 수 있습니다. 로그인과 생성 크레딧 정책은 바뀔 수 있으므로 사용 전 21st usage와 공식 요금 안내를 확인합니다.

21st login으로 만든 세션은 공식 문서 기준 ~/.config/21st/auth.json에 저장됩니다. 공용 PC에서는 작업 뒤 21st logout을 실행하고, API 키를 쓰는 경우 셸 기록이나 저장소의 .env 예시에 실제 값을 붙이지 않습니다. CLI는 명령 플래그, TWENTYFIRST_TOKEN, API_KEY_21ST, 저장된 로그인 순으로 자격 증명을 찾으므로 예전에 설정한 환경 변수가 어떤 계정으로 실행되는지 21st whoami로 먼저 확인합니다.

MCP에 설치 권한을 연결했다면 에이전트가 검색 결과를 곧바로 프로젝트에 쓰지 않도록 “먼저 --print 결과와 변경 예정 파일을 보여주고 승인 후 설치”라고 지시합니다. 마켓플레이스 코드는 제3자가 게시한 코드이므로 외부 요청, 추적 스크립트, 하드코딩된 키와 예기치 않은 폼 전송이 없는지도 코드 리뷰 대상입니다.

추천 활용 방식

21st.dev는 전체 사이트를 한 번에 교체하기보다 히어로, 가격표, 로그인 폼처럼 경계가 분명한 컴포넌트에 먼저 적용하는 것이 좋습니다. 설치 후 코드를 직접 소유하고 수정해야 하므로 구조를 이해한 뒤 공통 디자인 토큰과 테스트에 연결해야 유지보수가 쉬워집니다.