자주 묻는 질문
자주 묻는 질문과 문제 해결 가이드입니다.
문제 해결
HUA UX 컴포넌트의 스타일이 누락된 경우, Tailwind v4에게 패키지 파일을 스캔하도록 알려야 합니다.
@import "tailwindcss";
/* Add this line to scan HUA UX package */
@source "../node_modules/@hua-labs/hua-ux/dist/**/*.{js,mjs}";@source@source 지시어는 Tailwind에게 외부 패키지의 클래스 이름을 스캔하도록 알립니다.
빌드 중 "useToast must be used within ToastProvider" 오류가 발생하면 대신 useToastSafe를 사용하세요.
// Instead of useToast
import { useToastSafe } from '@hua-labs/hua-ux';
function MyComponent() {
const { addToast } = useToastSafe();
// Returns no-op functions when ToastProvider is not available
}useToastSafe useToastSafe는 SSR 중 no-op 함수를 반환하여 오류를 방지합니다.
이는 일반적으로 TypeScript가 서브패스 export를 해석할 수 없을 때 발생합니다. tsconfig.json을 업데이트하세요:
{
"compilerOptions": {
"moduleResolution": "bundler"
}
}"bundler" 해석 모드는 패키지 export 필드를 올바르게 처리합니다.
Next.js는 빌드 시 모든 라우트를 분석합니다. 코드가 모듈 레벨에서 클라이언트를 초기화하면 환경 변수를 사용할 수 없는 빌드 시에 실행됩니다.
// Bad: Runs at module load (build time)
const client = createClient(process.env.API_URL);
// Good: Lazy initialization
function getClient() {
return createClient(process.env.API_URL);
}런타임 환경 변수가 필요한 코드에는 지연 초기화 또는 동적 import를 사용하세요.
순환 종속성 경고가 보이면 패키지 import를 확인하세요. 일반적인 해결책:
- 순환 패키지에서 import하는 대신 공유 타입을 로컬에서 정의
- 공유 타입을 별도 패키지로 이동
- 직접 import 대신 종속성 주입 사용
// Circular: package-a imports package-b, package-b imports package-a
import { SomeType } from '@hua-labs/package-b';
// Solution: Define locally
interface SomeType {
// Define what you need
}Vercel은 기본적으로 이전 pnpm 버전을 사용합니다. corepack을 사용하여 버전을 지정하세요:
{
"installCommand": "corepack enable && corepack use pnpm@10.24.0 && pnpm install --frozen-lockfile"
}Vercel 대시보드 설정도 확인하세요 - vercel.json을 덮어쓸 수 있습니다.
모범 사례
콜론 구분자를 사용한 네임스페이스 기반 구성:
// File: translations/en/common.json
{
"nav": {
"home": "Home",
"about": "About"
},
"buttons": {
"save": "Save",
"cancel": "Cancel"
}
}
// Usage
t("common:nav.home") // → "Home"
t("common:buttons.save") // → "Save"리스트의 경우 순차 지연을 사용하세요. 스크롤 트리거 애니메이션의 경우 임계값을 조정하세요:
// Staggered list animation
{items.map((item, index) => {
const motion = useMotion({
type: 'slideUp',
duration: 400,
delay: index * 100, // 100ms stagger
});
return <div ref={motion.ref} style={motion.style}>{item}</div>;
})}
// Scroll-triggered with threshold
const motion = useMotion({
type: 'fadeIn',
threshold: 0.2, // Trigger when 20% visible
});HUA UX는 prefers-reduced-motion을 자동으로 존중합니다.
product: 대시보드 및 앱에 최적화됨
- 더 빠르고 미묘한 애니메이션 (300ms)
- 반복되는 상호작용을 위한 최소 모션
marketing: 랜딩 페이지에 최적화됨
- 더 표현력 있는 애니메이션 (500ms+)
- 첫인상을 위한 눈에 띄는 전환
Set colors in your hua-ux.config.ts에서 색상을 설정하세요:
export default defineConfig({
branding: {
name: 'My App',
colors: {
primary: '#0D9488', // Main brand color
secondary: '#14B8A6', // Secondary color
accent: '#06B6D4', // Accent color
},
},
});Access branding colors via useBranding() 훅 또는 var(--hua-primary)와 같은 CSS 변수를 통해 브랜딩 색상에 접근하세요.
여전히 도움이 필요하신가요?
찾고 계신 답변을 찾지 못하셨다면 언제든지 문의해 주세요: