시작하기

HUA Labs 패키지로 빠르게 시작하는 방법을 알아보세요.

알파 버전 안내

현재 패키지는 알파 버전입니다. 모노레포 외부에서 테스트 시 수동 설정 방법을 권장합니다.

패키지 선택

프로젝트에 맞는 패키지를 선택하세요.

@hua-labs/hua

1. Next.js 프로젝트 생성

새 Next.js 프로젝트를 생성하거나 기존 프로젝트를 사용하세요.

npxnpx create-next-app@latest my-app --typescript --tailwind --app

2. 패키지 설치

필요한 패키지를 설치하세요. hua는 모든 의존성을 포함합니다.

npmnpm install @hua-labs/hua zustand

yarnyarn add @hua-labs/hua zustand

pnpmpnpm add @hua-labs/hua zustand

3. 설정 파일 생성

프로젝트 루트에 hua.config.ts 파일을 생성하세요.

tsx

1// hua.config.ts
2import { defineConfig } from '@hua-labs/hua/framework/config';
3 
4export default defineConfig({
5  branding: {
6    name: 'My App',
7    colors: {
8      primary: 'hsl(220 90% 56%)',
9    },
10  },
11  i18n: {
12    defaultLanguage: 'en',
13    supportedLanguages: ['en', 'ko'],
14    namespaces: ['common'],
15    translationLoader: 'api',
16  },
17});

4. 레이아웃 설정

app/layout.tsx에 HuaProvider를 추가하세요.

tsx

1// app/layout.tsx
2import { ThemeProvider } from "@hua-labs/ui";
3import { HuaProvider } from "@hua-labs/hua/framework";
4import { setConfig } from "@hua-labs/hua/framework/config";
5import HuaConfig from "../hua.config";
6import "./globals.css";
7 
8// 설정 초기화
9setConfig(HuaConfig);
10 
11export default function RootLayout({
12  children,
13}: {
14  children: React.ReactNode;
15}) {
16  return (
17    <html lang="en" suppressHydrationWarning>
18      <body>
19        <ThemeProvider>
20          <HuaProvider config={HuaConfig}>
21            {children}
22          </HuaProvider>
23        </ThemeProvider>
24      </body>
25    </html>
26  );
27}

5. 번역 API 라우트 생성

i18n을 사용한다면 번역 API 라우트를 생성하세요.

tsx

1// app/api/translations/[language]/[namespace]/route.ts
2import { NextResponse } from "next/server";
3import fs from "fs";
4import path from "path";
5 
6export async function GET(
7  request: Request,
8  { params }: { params: Promise<{ language: string; namespace: string }> }
9) {
10  const { language, namespace } = await params;
11 
12  const filePath = path.join(
13    process.cwd(),
14    "public/translations",
15    language,
16    `${namespace}.json`
17  );
18 
19  try {
20    const content = fs.readFileSync(filePath, "utf-8");
21    return NextResponse.json(JSON.parse(content));
22  } catch {
23    return NextResponse.json({}, { status: 404 });
24  }
25}

6. 번역 파일 생성

public/translations 폴더에 번역 파일을 생성하세요.

json

1// public/translations/en/common.json
2{
3  "welcome": "Welcome",
4  "hello": "Hello, World!"
5}
6 
7// public/translations/ko/common.json
8{
9  "welcome": "환영합니다",
10  "hello": "안녕하세요!"
11}

7. 컴포넌트 사용

이제 컴포넌트와 훅을 사용할 수 있습니다!

tsx

1// app/page.tsx
2'use client';
3 
4import { Button, Card } from '@hua-labs/hua';
5import { useTranslation } from '@hua-labs/i18n-core';
6import { useMotion } from '@hua-labs/hua/framework';
7 
8export default function Page() {
9  const { t } = useTranslation();
10  const motion = useMotion({ type: 'fadeIn' });
11 
12  return (
13    <div ref={motion.ref} style={motion.style} className="p-8">
14      <Card className="p-6">
15        <h1 className="text-2xl font-bold mb-4">{t('common:welcome')}</h1>
16        <p className="mb-4">{t('common:hello')}</p>
17        <Button>Click me</Button>
18      </Card>
19    </div>
20  );
21}

다음 단계

문제 해결

하이드레이션 에러

i18n 설정에서 defaultLanguage가 SSR과 CSR에서 동일한지 확인하세요. suppressHydrationWarning을 html 태그에 추가하세요.

번역이 로드되지 않음

public/translations 폴더 구조와 API 라우트가 올바른지 확인하세요. 개발 서버를 재시작해보세요.

타입 에러

TypeScript 5.x 이상과 React 19 타입이 설치되어 있는지 확인하세요.