설치 및 사용

이 가이드 저장소의 설치·실행·배포 방법을 안내합니다. Next.js 16 App Router와 React 19로 개발하며, 문서는src/doc/의 JSX 파일로 관리하고 정적 사이트로 내보냅니다.

사전 요구사항

아래 환경이 설치되어 있어야 합니다.

도구	버전	비고
Node.js	20.9 이상	Next.js 16 실행 요구사항
pnpm	9.15.9	packageManager 필드에 명시된 버전

설치

저장소를 클론하고 프로젝트 루트에서 pnpm으로 의존성을 설치합니다.

# 저장소 클론
git clone <repository-url>
cd guide

# 의존성 설치
pnpm install

pnpm 스크립트

루트 package.json의 스크립트입니다.

명령	설명
`pnpm dev`	Turbopack 기반 Next.js 개발 서버 — http://localhost:3000
`pnpm build`	Turbopack 기반 Next.js 정적 export — out/ 생성
`pnpm start`	out/ 정적 빌드 결과를 로컬 서버로 실행
`pnpm preview`	out/ 정적 빌드 결과를 로컬 서버로 미리보기
`pnpm deploy:main`	/react로 빌드한 뒤 main/react/에 커밋·푸시

개발 서버

pnpm dev를 실행한 뒤 http://localhost:3000에 접속합니다. 파일을 수정하면 Next.js 개발 서버가 변경 내용을 자동으로 반영합니다.

pnpm dev

정적 빌드와 미리보기

next.config.mjs의 output: 'export' 설정에 따라 pnpm build가 서버 런타임이 필요 없는 정적 사이트를 out/에 생성합니다. pnpm preview로 배포 전에 결과물을 확인할 수 있습니다.

pnpm build
pnpm preview

하위 경로 빌드

사이트를 도메인 루트가 아닌 /react 같은 하위 경로에 배포할 때는 NEXT_PUBLIC_BASE_PATH를 지정합니다. 이 값은 Next.js basePath와 내부 링크에 적용됩니다.

# /react 하위 경로용 정적 사이트 생성
NEXT_PUBLIC_BASE_PATH=/react pnpm build

main 브랜치 배포

next 브랜치에서 pnpm deploy:main을 실행하면 /react 경로로 빌드한 뒤 main 브랜치의 react/ 폴더를 갱신하고 원격 저장소에 커밋·푸시합니다. 브랜치 전환과 원격 푸시가 포함되므로 배포 권한과 작업 상태를 먼저 확인하세요.

pnpm deploy:main

스타일 적용

이 가이드는app/layout.jsx에서 src/scss/main.scss를 불러오므로 Next.js 빌드에 전역 스타일이 포함됩니다.

다른 프로젝트에서 SCSS 소스를 직접 쓰려면 자체 빌드 도구의 Sass 설정에src/scss를 load path로 추가한 뒤src/scss/main.scss를 포함하거나 필요한 컴포넌트만 선택해서 불러옵니다.

// 전체 스타일
@use "main";

// 또는 필요한 컴포넌트만 선택
@use "tokens";
@use "themes";
@use "reset";
@use "components/button";
@use "components/input";
@use "components/alert";

컴포넌트 마크업 사용

각 컴포넌트 문서의 마크업 섹션 HTML은 어떤 프로젝트에도 복사해 사용할 수 있습니다. 클래스 이름과 ARIA 속성을 그대로 쓰면 스타일이 적용됩니다. 모달·드로어·아코디언 등 인터랙션이 필요한 컴포넌트는 React 컴포넌트 구현을 참고하거나, data-* 속성과 JS를 함께 포함합니다.

변경 사항이 저장되었습니다.

HTML 마크업 예시

React 없이 HTML·CSS만으로도 동일한 UI를 구성할 수 있습니다. 아래 마크업을 복사해 사용하세요.

<!-- Button 예시 -->
<button type="button" class="btn btn_filled color_primary">
  <span class="btn_label">저장</span>
</button>

<!-- Alert 예시 -->
<div class="alert color_info" role="alert">
  <div class="alert_body">
    <p class="alert_desc">변경 사항이 저장되었습니다.</p>
  </div>
</div>

테마

라이트/다크 테마는 data-theme 속성으로 전환됩니다.useThemehook(src/hooks/useTheme.js)이 헤더의 토글 버튼과localStorage를 관리합니다.

<!-- HTML 루트에 테마 지정 -->
<html lang="ko" data-theme="light">
<html lang="ko" data-theme="dark">

// React — useTheme hook (src/hooks/useTheme.js)
import { useTheme } from '@/hooks/useTheme';

function ThemeToggle() {
  const { theme, toggleTheme } = useTheme();
  return (
    <button type="button" onClick={toggleTheme}>
      {theme === 'dark' ? '라이트 모드' : '다크 모드'}
    </button>
  );
}

색상·간격 등 디자인 값은src/scss/_tokens.scss와 _themes.scss에서 CSS 변수로 정의됩니다. 전역 토큰의 기본값·사용 방법은디자인 토큰문서를 참고하세요.

새 컴포넌트 추가

컴포넌트와 문서를 새로 등록할 때 추가·수정하는 파일입니다. 문서 파일명은 URL slug와 동일하게 작성합니다.

파일	역할
`src/doc/components/{name}.jsx`	컴포넌트 문서 페이지 (docMeta export)
`src/components/{Name}.jsx`	재사용 UI 컴포넌트 (React)
`src/scss/components/_{name}.scss`	컴포넌트 스타일
`src/scss/components/_index.scss`	@use "{name}" 등록
`src/data/navigation.js`	사이드바 메뉴 항목 추가
`src/data/doc-registry.js`	정적 경로·페이지 메타데이터 등록
`src/utils/doc-loader.js`	문서 모듈 import 및 slug 매핑 등록

app/[[...slug]]/page.jsx는 src/data/doc-registry.js의 문서 목록으로 정적 경로를 생성하므로 새 컴포넌트를 추가할 때 라우트 페이지를 직접 수정하지 않습니다.