최대한의 생산성으로 개발팀이 함께 작업할 수 있는 통합 올인원 플랫폼을 원하시나요?
Apidog는 여러분의 모든 요구사항을 충족하며, 훨씬 저렴한 가격으로 Postman을 대체합니다!
프론트엔드 개발자에게 있어 미적으로 뛰어나고 성능이 우수하며 깊이 커스터마이징 가능한 사용자 인터페이스에 대한 요구는 그 어느 때보다 커졌습니다. 개발자들은 품질이나 창의적인 제어를 희생하지 않으면서 작업 흐름을 가속화할 수 있는 도구를 끊임없이 찾고 있습니다. 수년간 모놀리식 UI 컴포넌트 라이브러리가 커뮤니티에 잘 기여해 왔지만, 개발자 소유권, 모듈성, 최신 프레임워크와의 원활한 통합을 우선시하는 새로운 패러다임이 부상하고 있습니다. HeroUI는 바로 이 새로운 패러다임 속에서 자신만의 영역을 구축합니다.
HeroUI는 단순한 또 다른 컴포넌트 라이브러리가 아닙니다. 프로젝트에 직접 통합되도록 설계된 재사용 가능한 UI 컴포넌트의 세심하게 제작된 컬렉션입니다.1 개발자에게 코드베이스에 대한 궁극적인 제어권을 부여하는 철학을 지지합니다. 불투명한 컴포넌트를 노드 모듈에서 가져오는 대신, HeroUI 명령줄 인터페이스(CLI)를 사용하여 필요한 컴포넌트의 실제 소스 코드를 프로젝트에 추가합니다.2 이러한 "복사 및 붙여넣기"의 진화는 모든 버튼, 카드, 대화 상자가 자체 애플리케이션의 일부가 되어 특정 요구 사항에 맞게 조정, 재스타일링 및 적용할 준비가 되었음을 의미합니다.
React, Tailwind CSS, Next.js와 같은 거장들의 어깨 위에 구축된 HeroUI는 아름답고 접근 가능하며 반응형 사용자 인터페이스를 만들기 위한 빌딩 블록을 제공합니다. 속도와 특수성을 모두 중시하는 현대 개발자를 위해 설계되었으며, 엄격한 디자인 시스템에 얽매이지 않는 강력한 시작점을 제공합니다. 이 글은 HeroUI의 핵심 원리를 이해하고, 프로젝트에 설치하고, 모양과 느낌을 커스터마이징하고, 강력한 CLI를 활용하여 차세대 웹 애플리케이션을 구축하는 방법에 대한 포괄적인 가이드 역할을 할 것입니다.
파트 1: HeroUI 해부 - 철학과 핵심 기능
설치 및 사용의 기술적인 세부 사항에 들어가기 전에 HeroUI의 "이유"를 이해하는 것이 중요합니다. 어떤 문제를 해결하며, UI 도구의 혼잡한 분야에서 매력적인 선택이 되는 이유는 무엇일까요?
철학: 소유권과 타협 없는 커스터마이징
HeroUI와 Material-UI 또는 Ant Design과 같은 기존 UI 라이브러리의 근본적인 차이점은 소유권 개념에 있습니다. 기존 라이브러리를 설치하면 package.json
에 종속성을 추가하는 것입니다. 그러면 애플리케이션은 이 패키지에서 사전 컴파일된 컴포넌트를 가져옵니다. 이는 편리하지만 몇 가지 단점이 있습니다.
- 제한된 커스터마이징: 스타일 재정의는 복잡할 수 있으며, 종종
!important
태그나 복잡한 테마 제공자 구성으로 라이브러리의 기본 스타일에 맞서 싸워야 합니다. - 블랙박스 컴포넌트: 컴포넌트의 내부 로직은
node_modules
폴더에 숨겨져 있습니다. 예기치 않은 동작을 디버깅하거나 내부 작동 방식을 이해하는 것이 훨씬 더 어려워집니다. - 번들 크기 증가: 몇 개의 컴포넌트만 사용하더라도 라이브러리 전체 또는 상당 부분을 가져오는 경우가 많아 애플리케이션의 최종 번들 크기가 증가할 수 있습니다.
- 종속성 지옥: 라이브러리의 업데이트 주기와 해당 종속성에 얽매입니다. 라이브러리의 주요 변경 사항은 애플리케이션의 대규모 리팩토링을 강제할 수 있습니다.
HeroUI는 이러한 문제를 완전히 회피합니다. CLI가 컴포넌트의 소스 코드를 프로젝트 디렉토리(예: /components/ui
)에 직접 배치하도록 함으로써 몇 가지 주요 방식으로 개발자에게 권한을 부여합니다.
- 코드를 소유합니다: 이제 컴포넌트는 여러분의 것입니다. 구조, 스타일, 로직 등 무엇이든 변경할 수 있습니다. 인위적인 제한은 없습니다. 고유한 애니메이션이 있는 버튼이나 약간 다른 내부 구조가 필요한 경우 파일을 편집하기만 하면 됩니다.
- 완전한 투명성: 사용하는 모든 컴포넌트의 코드를 읽을 수 있습니다. 이는 학습, 디버깅 및 접근 가능하고 견고한 UI 요소를 구축하는 방법에 대한 더 깊은 이해를 얻는 데 매우 중요합니다.
- 사용되지 않는 코드 없음: 애플리케이션의 번들에는 명시적으로 추가한 컴포넌트만 포함됩니다. 그 이상은 없습니다.
- 분리 및 미래 보장: 컴포넌트가 코드베이스의 일부이므로 HeroUI의 버전 관리에 동일한 방식으로 묶이지 않습니다. 자체 일정에 따라 컴포넌트를 업데이트하거나 전혀 업데이트하지 않도록 선택할 수 있습니다.3
이 철학은 처음부터 시작하지 않고 제품을 위한 고유한 디자인 시스템을 구축하려는 개발자와 팀을 대상으로 합니다. 기초적인 스타일이 없는(또는 약간의 스타일이 적용된) 기본 요소를 제공하며, 브랜드 아이덴티티는 여러분이 제공합니다.
주요 기능 한눈에 보기
HeroUI는 단순히 설치 방법 그 이상입니다. 현대적인 개발 워크플로우를 위해 설계된 기능으로 가득합니다.4
- 풍부한 컴포넌트 컬렉션: HeroUI는 버튼, 폼, 대화 상자, 드롭다운, 데이터 테이블 등을 포함하여 가장 일반적으로 필요한 UI 컴포넌트의 포괄적인 세트를 제공합니다.5 각 컴포넌트는 접근성(ARIA 속성)과 사용자 경험을 염두에 두고 세심하게 설계되었습니다.6
- Tailwind CSS 기반: HeroUI 스타일링 기능의 핵심은 유틸리티 우선 CSS 프레임워크인 Tailwind CSS입니다. 이는 커스터마이징이 CSS 클래스를 재정의하는 것이 아니라 유틸리티 클래스를 조합하여 이루어진다는 것을 의미합니다. 이 접근 방식은 매우 빠르고 직관적이며 일관된 디자인 언어를 유지하는 데 도움이 됩니다. HeroUI는 Tailwind의 테마 기능을 최대한 활용하여 몇 줄의 구성만으로 프로젝트 전체 변경을 허용합니다.7
- 심층 테마 및 커스터마이징: 컴포넌트의 전체적인 모양과 느낌은 중앙 테마 구성을 통해 제어할 수 있습니다.8 여기에는 색상, 글꼴, 테두리 반경, 간격 등이 포함됩니다.9 이 모든 것은 CSS 변수를 통해 구현되며, 이는 다크 모드 구현과 같은 동적 테마를 매우 간단하게 만듭니다.
- 강력한 명령줄 인터페이스(CLI):
heroui-cli
는 HeroUI 생태계와 상호 작용하기 위한 기본 도구입니다.10 프로젝트 초기화를 처리하고, 새로운 컴포넌트를 추가하며, 프로젝트가 올바르게 구성되었는지 확인하여 수동 설정 시간을 절약해 줍니다.11 - 프레임워크 우선 통합: HeroUI는 최신 프레임워크와 원활하게 통합되도록 설계되었습니다.12 문서는 Next.js에 대한 일급 지원 및 가이드를 제공하며, React 생태계에서 가장 인기 있는 도구 내에서 잘 작동하겠다는 약속을 보여줍니다. React로 구축되었으며 Vite 또는 Create React App과 같은 다른 React 기반 프레임워크에 적용할 수 있습니다.13
- 기본 다크 모드: 다크 모드는 나중에 고려된 사항이 아닙니다. 전체 시스템은 다크 모드를 염두에 두고 구축되었으며, CSS 변수와 Tailwind의
dark:
변형을 활용하여 구현을 매우 간단하게 만듭니다. - TypeScript 및 RSC 지원: HeroUI는 TypeScript로 작성되어 즉시 뛰어난 타입 안전성을 제공합니다.14 또한 React Server Components(RSC)와 호환되어 Next.js 및 React 생태계의 최신 발전과 일치합니다.15
HeroUI는 누구를 위한 것인가?
HeroUI는 특정 유형의 개발자와 프로젝트에 이상적인 선택입니다.
- 제어권을 갈망하는 개발자: 컴포넌트 라이브러리의 경직성에 좌절한 적이 있다면 HeroUI는 신선한 공기처럼 느껴질 것입니다.
- 강력하고 고유한 브랜드 아이덴티티를 가진 프로젝트: 다른 모든 웹사이트와 똑같아 보이지 않는 사용자 정의 디자인 시스템을 구축하기 위한 완벽한 기반을 제공합니다.
- 스타트업 및 제품 팀: 빠르게 움직여야 하지만 확장 가능하고 유지 보수 가능한 프론트엔드 아키텍처를 구축하려는 팀은 HeroUI가 강력한 가속기임을 알게 될 것입니다.
- 학습 및 개발: 소스 코드를 얻을 수 있기 때문에 고품질의 접근 가능한 React 컴포넌트를 구축하는 방법을 배우는 데 훌륭한 도구입니다.
최소한의 구성만 필요한 "즉시 사용 가능한", 배터리 포함 솔루션을 선호하는 완전 초보자에게는 덜 적합할 수 있습니다. HeroUI의 힘은 구성 가능성에 있으며, 이는 Tailwind CSS 및 최신 프론트엔드 개발 환경에 대한 기본적인 이해를 요구합니다.
파트 2: 시작하기 - 설치 및 설정에 대한 자세한 안내
이제 철학을 이해했으니 실전에 돌입해 봅시다. 이 섹션에서는 HeroUI를 새 프로젝트 또는 기존 프로젝트에 통합하는 방법에 대한 세심하고 단계별 가이드를 제공합니다. 권장되고 가장 효율적인 방법은 공식 HeroUI CLI를 사용하는 것입니다.16
전제 조건
시작하기 전에 개발 환경이 다음 요구 사항을 충족하는지 확인하십시오.
- Node.js: 최신 버전의 Node.js가 설치되어 있어야 합니다(일반적으로 버전 18 이상).17 터미널에서
node -v
를 실행하여 버전을 확인할 수 있습니다. - 패키지 관리자:
npm
,yarn
또는pnpm
과 같은 패키지 관리자가 필요합니다.18 이 가이드에서는npm
에 포함된npx
를 사용합니다.19 - React 프레임워크 프로젝트: HeroUI는 React 프레임워크로 구축된 프로젝트에 추가되도록 설계되었습니다. 기본 가이드는 Next.js에 중점을 두지만 Vite 또는 Create React App과 같은 다른 프레임워크에도 적용할 수 있습니다. 최상의 경험을 위해 새 Next.js 프로젝트로 시작한다고 가정합니다. 다음 명령으로 프로젝트를 만들 수 있습니다: Bash
npx create-next-app@latest my-heroui-app
Next.js 설정 중에 TypeScript와 Tailwind CSS를 선택하는 것이 좋습니다. 이들은 HeroUI 생태계의 기본이 됩니다.
HeroUI CLI init
명령: 시작점
init
명령은 HeroUI 세계로 들어가는 마법 같은 진입점입니다. 프로젝트를 지능적으로 검사하고 일련의 질문을 한 다음 필요한 모든 것을 자동으로 구성합니다.
프로젝트 디렉토리로 이동합니다:Bash
cd my-heroui-app
이제 초기화 명령을 실행합니다:Bash
npx heroui-cli@latest init
이제 CLI가 설정 프로세스를 안내합니다. 각 질문과 선택 사항의 의미를 자세히 살펴보겠습니다.
1. "어떤 스타일을 사용하시겠습니까?"
- 옵션:
Default
,New York
- 설명: 이 선택은 컴포넌트의 기본 미학을 정의합니다.20
Default
는 더 현대적이고 미니멀한 스타일이며,New York
은 약간 더 전통적이고 기업적인 느낌을 제공합니다. 이 선택은 주로 CLI가 설정할 테두리 반경 및 간격과 같은 기본 스타일링에 영향을 미칩니다. 이 선택에 얽매이지 않으며, 나중에 완전히 커스터마이징할 수 있는 시작점일 뿐입니다. 깔끔한 시작을 위해Default
가 종종 좋은 선택입니다.
2. "기본 색상으로 어떤 색상을 사용하시겠습니까?"
- 옵션:
Slate
,Gray
,Zinc
,Neutral
,Stone
- 설명: HeroUI의 전체 색상 시스템은 중립 기본 색상의 음영을 기반으로 합니다. 이 선택은 배경, 텍스트, 테두리 및 컴포넌트 상태에 대한 기본 팔레트를 결정합니다. 예를 들어,
Slate
를 선택하면 UI에 시원하고 푸른 회색 톤이 적용되고,Stone
은 더 따뜻하고 흙빛 느낌을 제공합니다. CLI는 선택에 따라 전체 범위의 CSS 변수를 자동으로 생성합니다.
3. "전역 CSS 파일은 어디에 있습니까?"
- 기본값:
app/globals.css
(Next.js App Router용) 또는styles/globals.css
(Pages Router용). - 설명: CLI는 핵심 CSS 변수와 Tailwind 지시문을 어디에 삽입해야 하는지 알아야 합니다. 일반적으로 표준 Next.js 프로젝트에서 올바른 경로를 감지할 만큼 충분히 똑똑합니다. 비표준 프로젝트 구조를 가지고 있는 경우에만 변경해야 합니다.
4. "색상에 CSS 변수를 사용하시겠습니까?"
- 기본값:
Yes
- 설명: 거의 항상 예라고 대답해야 합니다. CSS 변수를 사용하는 것은 HeroUI 테마 시스템의 초석입니다.21 한 곳(
globals.css
)에서 색상 팔레트를 정의하고 어디서든 자동으로 적용되도록 할 수 있습니다.22 더 중요한 것은 다크 모드와 같은 동적 기능을 가능하게 하는 것입니다.
5. "tailwind.config.js
파일은 어디에 있습니까?"
- 기본값:
tailwind.config.js
- 설명: CLI는 HeroUI의 테마 프리셋 및 플러그인을 통합하기 위해 Tailwind 구성을 수정해야 합니다. 다시 말하지만, 자동으로 감지되어야 합니다.
6. "컴포넌트 가져오기 별칭 구성:"
- 기본값:
@/components
- 설명: 경로 별칭은 깔끔한 가져오기 구문을 위한 모범 사례입니다.23
import { Button } from '../../../components/ui/button'
대신import { Button } from '@/components/ui/button'
라고 작성할 수 있습니다. CLI는 컴포넌트에 사용할 별칭을 알아야tsconfig.json
(또는jsconfig.json
)에서 구성할 수 있습니다. 기본값@/components
는 합리적인 선택입니다.
7. "유틸리티 가져오기 별칭 구성:"
- 기본값:
@/lib/utils
- 설명: HeroUI는 몇 가지 유틸리티 함수에 의존하며, 가장 주목할 만한 것은 Tailwind 클래스를 조건부로 병합하는 함수(종종
cn
이라고 함)입니다. CLI는 이 유틸리티 파일을 생성하고 어디에 배치하고 어떤 별칭을 사용할지 알아야 합니다. 기본값@/lib/utils
는 표준입니다.
8. "React Server Components를 사용하고 있습니까?"
- 기본값: Next.js 버전 및 설정에 따라 자동 감지됩니다.
- 설명: 이는 App Router를 사용하는 최신 Next.js 애플리케이션에 매우 중요합니다.
Yes
라고 응답하면 CLI에 의해 추가된 컴포넌트에 필요한 경우"use client"
지시문이 포함됩니다. 이 지시문은 클라이언트 측 상호 작용(예:onClick
이벤트 처리 또는useState
와 같은 훅 사용)이 필요한 컴포넌트를 표시하여 React Server Components와 호환되도록 합니다.24
모든 질문에 답하면 CLI가 마법을 부립니다. 다음을 수행합니다.
- 필요한 종속성(
tailwindcss-animate
,class-variance-authority
,lucide-react
등)을 설치합니다. - 프로젝트 루트에
components.json
파일을 생성합니다. - 올바른 테마 설정으로
tailwind.config.js
를 수정합니다. - 기본 스타일과 선택한 색상 테마에 대한 모든 CSS 변수로
globals.css
를 채웁니다. - 구성한 경로 별칭으로
tsconfig.json
또는jsconfig.json
을 업데이트합니다. cn
유틸리티 함수가 포함된lib/utils.ts
파일을 생성합니다.
이제 프로젝트가 HeroUI를 사용할 준비가 완료되었습니다.
변경 사항 분석
CLI가 수정하거나 생성한 주요 파일을 자세히 살펴보겠습니다.
components.json
이 파일은 프로젝트 내 HeroUI의 매니페스트입니다. init
프로세스 중에 선택한 사항을 저장하고 프로젝트가 어떻게 구성되었는지 CLI에 알려줍니다.JSON
{
"$schema": "https://www.heroui.com/schema.json",
"style": "default",
"rsc": true,
"tsx": true,
"tailwind": {
"config": "tailwind.config.js",
"css": "app/globals.css",
"baseColor": "slate",
"cssVariables": true
},
"aliases": {
"utils": "@/lib/utils",
"components": "@/components"
}
}
이 파일을 수동으로 편집해야 하는 경우는 거의 없지만, 그 목적을 이해하는 것은 도움이 됩니다. 이는 CLI 작업의 핵심입니다.
tailwind.config.js
Tailwind 구성은 다음과 같이 확장됩니다. 주요 추가 사항은 theme
확장과 tailwindcss-animate
플러그인입니다.JavaScript
/** @type {import('tailwindcss').Config} */
module.exports = {
darkMode: ["class"],
content: [
'./pages/**/*.{ts,tsx}',
'./components/**/*.{ts,tsx}',
'./app/**/*.{ts,tsx}',
'./src/**/*.{ts,tsx}',
],
theme: {
container: {
center: true,
padding: "2rem",
screens: {
"2xl": "1400px",
},
},
extend: {
colors: {
border: "hsl(var(--border))",
input: "hsl(var(--input))",
// ... and many more color definitions linked to CSS variables
primary: {
DEFAULT: "hsl(var(--primary))",
foreground: "hsl(var(--primary-foreground))",
},
// ...
},
borderRadius: {
lg: "var(--radius)",
md: "calc(var(--radius) - 2px)",
sm: "calc(var(--radius) - 4px)",
},
keyframes: {
// ... keyframes for animations
},
animation: {
// ... animation utilities
},
},
},
plugins: [require("tailwindcss-animate")],
}
primary
와 같은 색상이 헥스 코드가 아닌 hsl(var(--primary))
로 정의된 방식에 주목하십시오. 이는 Tailwind에게 전역 CSS에 정의된 --primary
라는 CSS 변수를 사용하도록 지시합니다.
app/globals.css
이 파일은 이제 디자인 시스템 테마의 핵심입니다. 기본 Tailwind 지시문과 대량의 CSS 변수를 포함합니다.CSS
@tailwind base;
@tailwind components;
@tailwind utilities;
@layer base {
:root {
--background: 0 0% 100%;
--foreground: 222.2 84% 4.9%;
--card: 0 0% 100%;
/* ... many more variables for the light theme */
--radius: 0.5rem;
}
.dark {
--background: 222.2 84% 4.9%;
--foreground: 210 40% 98%;
--card: 222.2 84% 4.9%;
/* ... many more variables for the dark theme */
}
}
여기서 이 설정의 강력함을 볼 수 있습니다. 모든 라이트 테마 색상은 :root
범위에 정의되고, 모든 다크 테마 색상은 .dark
클래스 범위 내에 정의됩니다. <html>
요소에 .dark
클래스가 추가되면 브라우저는 자동으로 다크 테마 변수를 사용합니다.
파트 3: 커스터마이징 마스터하기 - 테마, 레이아웃 및 다크 모드
HeroUI가 초기화되면 진짜 재미가 시작됩니다: 나만의 것으로 만들기. 아키텍처는 깊고 직관적인 커스터마이징을 위해 명시적으로 설계되었습니다.25
CSS 변수를 사용한 테마 아트
HeroUI의 테마는 다른 라이브러리에서 볼 수 있는 복잡한 JavaScript 기반 테마 객체와 다릅니다. 더 간단하고 강력하며 최신 CSS 기능을 활용합니다. 전체 테마(색상, 테두리 반경, 글꼴)는 globals.css
파일에 정의된 CSS 변수에 의해 제어됩니다.
색상 변경
기본 브랜드 색상을 변경하고 싶다고 가정해 봅시다. Tailwind 구성으로 이동할 필요가 없습니다. globals.css
에서 관련 CSS 변수를 찾아 값을 변경하기만 하면 됩니다.
색상은 HSL(색조, 채도, 명도) 값을 사용하여 정의되지만 hsl()
래퍼는 없습니다. 예:CSS
:root {
/* ... */
--primary: 221.2 83.2% 53.3%;
--primary-foreground: 210 40% 98%;
/* ... */
}
.dark {
/* ... */
--primary: 217.2 91.2% 59.8%;
--primary-foreground: 210 40% 98%;
/* ... */
}
기본 색상을 생생한 녹색으로 변경하려면 온라인 색상 선택기를 사용하여 선택한 색상의 HSL 값을 찾고 변수를 업데이트할 수 있습니다:CSS
/* In globals.css */
:root {
/* ... */
--primary: 142.1 76.2% 36.3%; /* New Green Primary Color */
--primary-foreground: 355.7 100% 97.3%; /* A contrasting light color for text on the primary color */
/* ... */
}
.dark {
/* ... */
--primary: 142.1 70.2% 46.3%; /* A slightly different green for dark mode */
--primary-foreground: 355.7 100% 97.3%;
/* ... */
}
이 파일을 저장하면 "primary" 색상을 사용하는 모든 컴포넌트(예: <Button>
)가 애플리케이션 전체에서 즉시 업데이트되어 이 새로운 녹색 색상을 반영합니다. 이는 매우 강력합니다.
테두리 반경 변경
카드 및 입력과 같은 컴포넌트 모서리의 둥근 정도는 단일 CSS 변수인 --radius
에 의해 제어됩니다.CSS
/* In globals.css */
:root {
/* ... */
--radius: 0.5rem; /* The default value */
}
더 날카롭고 각진 모양을 선호한다면 이 값을 줄일 수 있습니다:CSS
:root {
--radius: 0.25rem; /* Less rounded */
}
또는 매우 부드럽고 둥근 미학을 위해 값을 늘릴 수 있습니다:CSS
:root {
--radius: 1.5rem; /* Very rounded */
}
이 한 줄 변경은 모든 컴포넌트에 적용되어 UI 전체에서 일관된 테두리 반경을 보장합니다.
새 색상 추가
init
명령으로 제공되는 색상에 제한되지 않습니다. 자신만의 의미 있는 색상을 쉽게 추가할 수 있습니다. 예를 들어, "special" 브랜드 색상을 추가해 보겠습니다.
globals.css
에 CSS 변수 정의:CSS
/* In globals.css */
:root {
/* ... */
--special: 320 86% 59%;
--special-foreground: 330 100% 98%;
}
.dark {
/* ... */
--special: 320 80% 69%;
--special-foreground: 330 100% 98%;
}
tailwind.config.js
에서 Tailwind에 노출:JavaScript
// In tailwind.config.js
// ...
extend: {
colors: {
// ...
special: {
DEFAULT: "hsl(var(--special))",
foreground: "hsl(var(--special-foreground))",
},
},
},
// ...
이제 bg-special
및 text-special-foreground
와 같은 Tailwind의 유틸리티 클래스를 사용하여 컴포넌트에서 이러한 색상을 사용할 수 있습니다.
반응형 레이아웃 구축
HeroUI 컴포넌트는 Tailwind CSS로 구축되었으므로 본질적으로 반응형입니다.26 Tailwind의 반응형 접두사(sm:
, md:
, lg:
, xl:
)를 모든 유틸리티 클래스에 사용하여 다양한 화면 크기에서 컴포넌트 스타일을 변경할 수 있습니다.27
데스크톱에서는 보이지만 모바일에서는 접히는 사이드바가 있는 간단한 페이지 레이아웃을 구축한다고 상상해 봅시다. HeroUI는 저수준 컴포넌트(Card
, Button
)를 제공하지만, 이를 더 큰 레이아웃으로 구성하는 것은 여러분의 책임입니다.
다음은 Next.js 페이지 컴포넌트에서 이를 구성하는 방법의 예입니다:TypeScript
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { Button } from "@/components/ui/button";
export default function DashboardPage() {
return (
<div className="flex min-h-screen flex-col md:flex-row">
{/* Sidebar */}
<aside className="w-full border-b bg-muted p-4 md:w-64 md:border-b-0 md:border-r">
<h2 className="text-lg font-semibold">Navigation</h2>
<nav className="mt-4 flex flex-row space-x-2 md:flex-col md:space-x-0 md:space-y-2">
<Button variant="ghost" className="justify-start">Dashboard</Button>
<Button variant="ghost" className="justify-start">Settings</Button>
<Button variant="ghost" className="justify-start">Profile</Button>
</nav>
</aside>
{/* Main Content */}
<main className="flex-1 p-8">
<h1 className="text-4xl font-bold tracking-tight">Dashboard</h1>
<p className="mt-2 text-muted-foreground">
Welcome to your dashboard.
</p>
<div className="mt-8 grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
<Card>
<CardHeader>
<CardTitle>Revenue</CardTitle>
</CardHeader>
<CardContent>
<p className="text-3xl font-bold">$45,231.89</p>
</CardContent>
</Card>
<Card>
<CardHeader>
<CardTitle>Subscriptions</CardTitle>
</CardHeader>
<CardContent>
<p className="text-3xl font-bold">+2350</p>
</CardContent>
</Card>
<Card>
<CardHeader>
<CardTitle>Active Users</CardTitle>
</CardHeader>
<CardContent>
<p className="text-3xl font-bold">+573</p>
</CardContent>
</Card>
</div>
</main>
</div>
);
}
이 예시에서:
- 메인 컨테이너는
flex
컨테이너입니다. 모바일(flex-col
)에서는 사이드바가 위에 있습니다. 중간 화면 이상(md:flex-row
)에서는 나란히 레이아웃으로 전환됩니다. aside
는 모바일에서 전체 너비(w-full
)를 가지지만 데스크톱에서는 고정 너비(md:w-64
)를 가집니다.- 메인 콘텐츠 영역은 화면 크기에 따라 열 수를 조정하는
grid
레이아웃을 사용합니다(sm:grid-cols-2
,lg:grid-cols-3
).
이는 핵심 원리를 보여줍니다: HeroUI는 스타일이 적용된 기본 요소(Card
, Button
)를 제공하며, Tailwind CSS의 모든 기능을 사용하여 이를 반응형의 복잡한 레이아웃으로 배치합니다.28
완벽한 다크 모드 구현
HeroUI의 가장 우아한 기능 중 하나는 내장된 다크 모드 지원입니다.29 init
명령이 이미 라이트(:root
) 및 다크(.dark
) 테마 모두에 대한 색상 변수를 설정했기 때문에 구현이 놀랍도록 간단합니다.
가장 일반적인 접근 방식은 테마 전환을 처리하고 로컬 스토리지에 사용자 선택을 유지하는 next-themes
패키지를 사용하는 것입니다.
next-themes
설치:Bash
npm install next-themes
테마 제공자 생성:
예를 들어, components/theme-provider.tsx에 새 파일을 생성합니다.TypeScript
"use client";
import * as React from "react";
import { ThemeProvider as NextThemesProvider } from "next-themes";
import { type ThemeProviderProps } from "next-themes/dist/types";
export function ThemeProvider({ children, ...props }: ThemeProviderProps) {
return <NextThemesProvider {...props}>{children}</NextThemesProvider>;
}
제공자로 루트 레이아웃 감싸기:
Next.js 루트 레이아웃(app/layout.tsx)에서 ThemeProvider를 가져와 사용합니다.30TypeScript
import { ThemeProvider } from "@/components/theme-provider";
import type { Metadata } from "next";
import { Inter } from "next/font/google";
import "./globals.css";
const inter = Inter({ subsets: ["latin"] });
export const metadata: Metadata = {
title: "Create Next App",
description: "Generated by create next app",
};
export default function RootLayout({
children,
}: Readonly<{
children: React.ReactNode;
}>) {
return (
<html lang="en" suppressHydrationWarning>
<body className={inter.className}>
<ThemeProvider
attribute="class"
defaultTheme="system"
enableSystem
disableTransitionOnChange
>
{children}
</ThemeProvider>
</body>
</html>
);
}
여기서 주요 속성은 다음과 같습니다.
attribute="class"
:next-themes
에게<html>
요소에 클래스를 추가/제거하여 테마를 토글하도록 지시합니다.31defaultTheme="system"
: 사용자 운영 체제 기본 설정에 따라 테마를 자동으로 설정합니다.enableSystem
: "시스템" 테마 옵션을 활성화합니다.
테마 토글 버튼 생성:
이제 사용자가 테마를 전환할 수 있도록 UI 요소만 있으면 됩니다.TypeScript
"use client";
import * as React from "react";
import { Moon, Sun } from "lucide-react";
import { useTheme } from "next-themes";
import { Button } from "@/components/ui/button";
export function ModeToggle() {
const { setTheme, theme } = useTheme();
const toggleTheme = () => {
setTheme(theme === "light" ? "dark" : "light");
};
return (
<Button variant="outline" size="icon" onClick={toggleTheme}>
<Sun className="h-[1.2rem] w-[1.2rem] rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
<Moon className="absolute h-[1.2rem] w-[1.2rem] rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
<span className="sr-only">Toggle theme</span>
</Button>
);
}
이32 컴포넌트는 next-themes
의 useTheme
훅을 사용하여 현재 테마를 확인하고 새 테마를 설정합니다. 회전하는 해와 달 아이콘은 멋진 시각적 전환을 제공합니다. 이 <ModeToggle />
컴포넌트를 UI의 어딘가(예: 헤더)에 배치하기만 하면 완전히 기능하는 영구적인 다크 모드 토글이 완성됩니다.
파트 4: HeroUI CLI와 컴포넌트 중심 워크플로우
heroui-cli
는 단순한 설치 프로그램 그 이상입니다. 컴포넌트 라이브러리를 관리하고 확장하는 데 사용할 기본 도구입니다. 초기화 후 주요 목적은 프로젝트에 새로운 컴포넌트를 추가하는 것입니다.33
컴포넌트 추가: 핵심 워크플로우
애플리케이션에 대화 상자 모달이 필요하다고 가정해 봅시다. 처음부터 작성하는 대신 CLI에 HeroUI의 사전 구축된 접근 가능한 Dialog
컴포넌트를 추가하도록 요청할 수 있습니다.
명령은 간단합니다:Bash
npx heroui-cli@latest add dialog
CLI는 다음 작업을 수행합니다.
- 프로젝트 구조(경로 별칭, TypeScript 사용 등)를 이해하기 위해
components.json
파일을 읽습니다. Dialog
컴포넌트 및 해당 종속성(예:Dialog
는Button
에 의존할 수 있음)의 최신 소스 코드를 가져옵니다.- 컴포넌트 파일을 컴포넌트 디렉토리에 직접 배치합니다. 예:
components/ui/dialog.tsx
. - 설치해야 할 다른 종속성이 있으면 알려줍니다.
이제 프로젝트에 dialog.tsx
파일이 있습니다. 코드를 검사하고, 배우고, 심지어 수정할 수도 있습니다.34 기본 Dialog
에 마음에 들지 않는 전환 효과가 있다면 파일을 열어 애니메이션을 제어하는 Tailwind 클래스를 변경하기만 하면 됩니다. 이러한 수준의 제어는 HeroUI 경험의 초석입니다.
한 번에 여러 컴포넌트를 추가할 수 있습니다:Bash
npx heroui-cli@latest add card button input label
이 명령은 네 가지 컴포넌트와 해당 종속성을 한 번에 프로젝트에 추가합니다.
CLI API 이해: components.json
components.json
파일은 프로젝트와 HeroUI CLI 간의 계약입니다. 속성을 다시 살펴보며 CLI 동작에 어떻게 영향을 미치는지 이해해 봅시다.
$schema
: 최신 코드 편집기에서components.json
파일에 대한 IntelliSense 및 유효성 검사를 제공합니다.style
: 컴포넌트 코드를 가져올 때 어떤 기본 스타일(default
또는new-york
)을 사용할지 CLI에 알려 스타일 일관성을 보장합니다.rsc
: CLI가 컴포넌트에"use client"
지시문을 추가해야 하는지 여부를 결정합니다. 이는 Next.js App Router 호환성에 중요합니다.tsx
: CLI에게 컴포넌트 파일의 TypeScript(.tsx
) 또는 JavaScript(.jsx
) 버전을 가져올지 여부를 알려줍니다.tailwind
:config
:tailwind.config.js
파일의 경로입니다. CLI는 향후 업데이트 또는 분석을 위해 이 정보가 필요할 수 있습니다.css
: 변수가 저장된 전역 CSS 파일의 경로입니다.baseColor
:init
중에 선택한 중립 색상 팔레트입니다.cssVariables
: 프로젝트가 테마에 CSS 변수를 사용하도록 설정되었음을 확인합니다.aliases
:utils
:cn
함수와 같은 공유 유틸리티에 대한 가져오기 경로를 정의합니다. CLI가 이 유틸리티가 필요한 컴포넌트를 추가할 때 가져오기 구문에 이 별칭을 사용합니다.components
: UI 컴포넌트 자체에 대한 가져오기 경로를 정의합니다. 이를 통해 컴포넌트가 깔끔하고 일관된 경로를 사용하여 다른 컴포넌트를 가져올 수 있습니다(예:Dialog
는Button
을 가져올 수 있음).
이 구성을 이해하면 프로젝트 구조를 리팩토링하기로 결정한 경우(예: 컴포넌트 디렉토리를 @/components
에서 @/ui
로 이동) CLI의 동작을 수동으로 조정할 수도 있습니다.
결론: HeroUI로 나만의 방식으로 구축하기
HeroUI는 개발자가 UI 라이브러리를 생각하고 사용하는 방식에 있어 상당한 변화를 나타냅니다. 일률적이고 블랙박스 모델에서 벗어나 투명하고 권한을 부여하며 깊이 커스터마이징 가능한 개발자 경험으로 나아갑니다. 스타일이 적용되지 않은 접근 가능한 컴포넌트를 소스 코드로 직접 제공함으로써 빠른 개발과 맞춤형 디자인 사이의 완벽한 균형을 이룹니다.
HeroUI의 핵심 강점은 분명합니다.
- 궁극적인 소유권: 컴포넌트는 여러분의 코드입니다. 제한 없이 수정, 확장 및 적용할 수 있습니다.
- 심층 커스터마이징: CSS 변수를 기반으로 하는 강력한 테마 시스템은 애플리케이션 전체에서 색상, 간격 및 반경을 쉽게 변경할 수 있게 합니다.35
- 현대적인 아키텍처: TypeScript, Tailwind CSS로 구축되었으며 Next.js 및 React Server Components에 대한 일급 지원을 제공하여 웹 개발의 미래를 위해 설계된 도구입니다.36
- 개발자 친화적인 도구: 지능적인 CLI는 지루한 설정 프로세스를 자동화하고 새로운 컴포넌트 추가를 원활한 경험으로 만듭니다.37
HeroUI는 사용자 인터페이스가 제품 아이덴티티의 핵심 부분이라고 믿는 빌더, 장인, 팀을 위한 것입니다. 완성된 집을 제공하는 것이 아니라 꿈의 집을 짓기 위한 최고 품질의 재료와 완벽하게 정리된 작업장을 제공합니다. 독특하고 세련되며 유지 보수 가능한 프론트엔드가 필요한 다음 프로젝트에는 HeroUI를 고려하십시오. 아직 가장 영웅적인 UI를 구축할 수 있도록 지원하는 도구가 될 수 있습니다.
최대한의 생산성으로 개발팀이 함께 작업할 수 있는 통합 올인원 플랫폼을 원하시나요?
Apidog는 여러분의 모든 요구사항을 충족하며, 훨씬 저렴한 가격으로 Postman을 대체합니다!