개발 워크플로우

개발 서버

pnpm dev

다음 기능과 함께 Vite 개발 서버 실행:

• Hot module replacement
• Fast refresh
• Source maps
• 포트 5173

컴포넌트 개발

위치

컴포넌트는 목적별로 구성됩니다:

src/components/
├── layout/          # AppShell, Navbar
├── ui/              # Button, Card, Badge
├── Alert.js
├── BusinessCard.js
├── CategoryFilter.js
├── PostcodeSelect.js
└── ...

컴포넌트 생성

VanJS 함수형 컴포넌트 사용:

import van from 'vanjs-core';
const { div, button } = van.tags;

export function MyComponent({ title }) {
  const count = van.state(0);
  
  return div(
    { class: 'my-component' },
    button(
      { 
        onclick: () => count.val++,
        class: 'btn btn-primary'
      },
      () => `Count: ${count.val}`
    )
  );
}

스타일링

Tailwind v4 유틸리티 클래스 사용:

div({ class: 'flex items-center gap-4 p-4 rounded-lg bg-background' })

shadcn/ui 디자인 토큰은 CSS 변수를 통해 사용 가능합니다.

상태 관리

VanJS 반응형 상태:

const state = van.state(initialValue);
state.val = newValue;  // 업데이트
const current = state.val;  // 읽기

파생 상태:

van.derive(() => {
  // 의존성 변경 시 실행
  console.log(state.val);
});

라우팅

src/lib/router.js의 해시 기반 라우팅:

import { navigate } from './lib/router.js';

// 프로그래매틱 네비게이션
navigate('/business/1234567890');

// 해시 링크
a({ href: '#/docs' }, 'Docs')

데이터 로딩

인덱스 (시작 시)

import { loadAllIndices } from './lib/dataLoader.js';

await loadAllIndices();
// 로드: postcode_index, category_index, classifications

Progressive Loading

import { loadPostcode } from './lib/postcodeLoader.js';

const businesses = await loadPostcode('06234');
// 반환: _shard 메타데이터가 포함된 사업자 배열

상세 보기

import { loadBusinessDetails } from './lib/dataLoader.js';

const details = await loadBusinessDetails(business);
// business._shard를 사용하여 샤드 직접 페치

테스트

테스트 실행:

pnpm test

워치 모드:

pnpm test:watch

Vitest를 사용한 테스트 구조:

import { describe, it, expect } from 'vitest';

describe('MyComponent', () => {
  it('renders correctly', () => {
    const el = MyComponent({ title: 'Test' });
    expect(el).toBeDefined();
  });
});

빌드

프로덕션 빌드:

pnpm build

출력: dist/

미리보기:

pnpm preview

코드 스타일

• 불변성: 항상 새 객체 생성
• 작은 함수: <50줄
• 명확한 이름: 설명적이고 축약 없이
• 에러 처리: 명시적 try/catch
• 주석: "왜"만 작성, "무엇"은 작성하지 않음

일반 작업

새 페이지 추가

1. src/pages/MyPage.js 생성
2. src/lib/router.js에 라우트 추가
3. src/components/layout/Navbar.js에 네비게이션 링크 추가

분류 체계 추가

1. bizcat/ 또는 prdcat/에서 JSON 생성
2. public/data/로 복사
3. dataLoader.loadCategoryMetadata() 업데이트

스타일 업데이트

전역 스타일은 src/index.css를 편집하거나 Tailwind 유틸리티를 인라인으로 사용하세요.

디버깅

디버그 로깅 활성화:

console.log('[dataLoader.js] Loading postcode:', postcode);

JSONL 로딩 패턴을 확인하려면 DevTools에서 네트워크 요청을 확인하세요.

OpenBSD 참고사항

scripts/의 플랫폼별 스크립트:

• install-tailwind-openbsd.sh - lightningcss 및 @tailwindcss/oxide 패치
• install-rolldown-openbsd.sh - rolldown 바인딩 패치

pnpm install 후 매번 실행하세요.