설정

stable

createDotConfig()로 토큰 재정의, 커스텀 브레이크포인트, 캐시 설정 관리

@hua-labs/dotv2.0.0

Import

import { createDotConfig, clearDotCache } from '@hua-labs/dot';
import type { DotUserConfig, DotConfig } from '@hua-labs/dot';

Functions

createDotConfig

전역 토큰 설정을 재정의합니다. 기본 토큰과 딥 머지되어 적용됩니다. 호출 시 내부 캐시가 자동으로 재생성됩니다.

Signature

function createDotConfig(userConfig?: DotUserConfig): DotConfig

Parameters

파라미터	타입	설명
`userConfig`	`DotUserConfig`	사용자 설정 오브젝트

DotUserConfig

필드	타입	기본값	설명
`runtime`	`'web' \	'native' \	'flutter'`	`'web'`	기본 대상 플랫폼
`theme`	`ThemeConfig`	`{}`	토큰 재정의
`cache`	`boolean`	`true`	캐시 활성화 여부
`cacheSize`	`number`	`500`	입력 레벨 캐시 최대 항목 수
`strictMode`	`boolean`	`false`	알 수 없는 토큰에서 오류 발생
`warnUnknown`	`boolean`	`NODE_ENV === 'development'`	알 수 없는 토큰 경고
`breakpoints`	`string[]`	`['sm','md','lg','xl','2xl']`	커스텀 브레이크포인트 이름 목록 (모바일 퍼스트 순서)
`breakpointWidths`	`Record<string, string>`	기본 Tailwind 폭	브레이크포인트별 min-width
`remBase`	`number`	`16`	네이티브 어댑터의 rem/em 변환 기준값

ThemeConfig

필드	타입	설명
`colors`	`Record<string, Record<string, string> \	string>`	색상 팔레트 재정의
`spacing`	`Record<string, string>`	스페이싱 스케일 재정의
`borderRadius`	`Record<string, string>`	테두리 반경 재정의
`fontSize`	`Record<string, string>`	폰트 크기 재정의
`fontWeight`	`Record<string, string \	number>`	폰트 두께 재정의
`fontFamily`	`Record<string, string>`	폰트 패밀리 재정의
`shadows`	`Record<string, string>`	그림자 재정의
`gridCols`	`Record<string, string>`	그리드 컬럼 재정의
`semanticColors`	`string[] \	Record<string, string>`	CSS 변수 기반 시맨틱 색상
`semanticPrefix`	`string`	시맨틱 색상 CSS 변수 접두사 (기본: `'--color'`)

Returns

DotConfig — 기본값과 딥 머지된 전체 해석 설정.

Usage

import { createDotConfig, dot } from '@hua-labs/dot';

// 커스텀 색상 토큰 추가
createDotConfig({
  theme: {
    colors: {
      brand: {
        50: '#f0e6ff',
        100: '#d9b3ff',
        500: '#6630E6',
        900: '#2d0080',
      },
    },
  },
});

dot('bg-brand-500 text-brand-50');
// { backgroundColor: '#6630E6', color: '#f0e6ff' }

// 스페이싱 스케일 확장
createDotConfig({
  theme: {
    spacing: {
      '18': '72px',
      '22': '88px',
      '128': '512px',
    },
  },
});

dot('p-18 w-128');
// { padding: '72px', width: '512px' }

// 커스텀 브레이크포인트
createDotConfig({
  breakpoints: ['mobile', 'tablet', 'desktop', 'wide'],
  breakpointWidths: {
    mobile: '375px',
    tablet: '768px',
    desktop: '1280px',
    wide: '1536px',
  },
});

dot('p-4 tablet:p-8 desktop:p-12', { breakpoint: 'desktop' });
// { padding: '48px' }

// dotClass도 커스텀 브레이크포인트 사용 (syncClassConfig 필요)
import { syncClassConfig } from '@hua-labs/dot/class';
syncClassConfig();

// React Native — remBase 설정
createDotConfig({
  runtime: 'native',
  remBase: 16,
});

dot('p-4');
// { padding: 16 }  ← 16px → 16 (number)

// Flutter 전역 대상
createDotConfig({
  runtime: 'flutter',
});

dot('p-4 bg-blue-500');
// FlutterRecipe { padding: { top: 16, ... }, decoration: { color: '#3b82f6' } }

// 시맨틱 색상 — CSS 변수 기반
createDotConfig({
  theme: {
    semanticColors: {
      background: 'var(--color-background)',
      foreground: 'var(--color-foreground)',
      primary: 'var(--color-primary)',
      'primary-foreground': 'var(--color-primary-foreground)',
    },
  },
});

dot('bg-background text-foreground');
// { backgroundColor: 'var(--color-background)', color: 'var(--color-foreground)' }

// 또는 string[] 단축 형식 (auto-mapped to var(--color-*))
createDotConfig({
  theme: {
    semanticColors: ['sidebar', 'sidebar-foreground', 'chart-1'],
  },
});
// { sidebar: 'var(--color-sidebar)', 'sidebar-foreground': 'var(--color-sidebar-foreground)', 'chart-1': 'var(--color-chart-1)' }

// strictMode — 알 수 없는 토큰에서 오류 발생
createDotConfig({ strictMode: true });

try {
  dot('unknown-utility');  // throws Error
} catch (e) {
  console.error(e.message);
}

// warnUnknown — 개발 환경 경고
createDotConfig({ warnUnknown: true });
dot('typo-4');  // console.warn 출력

clearDotCache

입력 레벨 캐시와 토큰 레벨 캐시를 모두 초기화합니다. 설정 변경 후 또는 메모리 관리를 위해 호출합니다.

Signature

function clearDotCache(): void

Usage

import { createDotConfig, clearDotCache, dot } from '@hua-labs/dot';

// createDotConfig()는 내부적으로 캐시를 재생성하므로
// 일반적인 설정 변경에는 별도 clearDotCache() 불필요

// 수동 캐시 초기화가 필요한 경우
clearDotCache();

// 메모리 사용량이 걱정될 때
if (typeof window !== 'undefined' && performance.memory?.usedJSHeapSize > THRESHOLD) {
  clearDotCache();
}

Notes

createDotConfig()는 모듈 레벨 싱글톤에 설정을 적용합니다. 모든 이후 dot(), dotMap(), dotExplain() 호출에 영향을 줍니다.
테마 토큰은 기본값과 딥 머지됩니다. colors를 재정의할 때 기존 색상 팔레트(gray, blue, red 등)가 사라지지 않습니다.
breakpoints 배열은 교체됩니다(딥 머지 아님). 기본 Tailwind 브레이크포인트를 유지하려면 기존 브레이크포인트를 포함시키세요.
Next.js에서는 app/providers.tsx 또는 _app.tsx에서 앱 초기화 시 한 번 호출하세요.