@thefreshop/tb — tb framework

1) 패키지 이름 + 한 줄 소개

Ant Design 기반의 React UI 프레임워크로, 탭형 어드민 프레임과 CRUD 테이블/검색/페이지 스캐폴드를 제공합니다.

2) Why / What it solves

• 탭 기반 어드민 프레임(Top/Nav/Bottom)과 라우팅을 빠르게 구성.
• 검색/테이블/모달 CRUD 흐름을 재사용 가능한 컴포넌트로 표준화.
• Ant Design을 기반으로 일관된 관리자 UI 구축.

3) Features

• [x] 탭 기반 프레임 레이아웃 + 동적 라우팅
• [x] 세션 기반 탭 상태 저장(sessionStorage)
• [x] 검색 박스 + 테이블 + 로딩 레이아웃 스캐폴드
• [x] Ant Design Table 기반 CRUD 래퍼 + 모달 생성/수정
• [x] 한국어 로케일 기본 제공(dayjs/moment/antd)

4) Installation

npm i @thefreshop/tb

yarn add @thefreshop/tb

pnpm add @thefreshop/tb

Peer Dependencies

이 패키지는 아래 피어 의존성을 필요로 합니다:

npm i react react-dom react-router antd @ant-design/icons dayjs moment react-error-boundary @monaco-editor/react

5) Quick Start

import React from "react";
import { TbProvider, TbpProvider, TbFrame } from "@thefreshop/tb";
import type { navType, topType, tbframeType } from "@thefreshop/tb";

const setting: tbframeType = { islogin: false, startTabKey: "dashboard" };
const top: topType = { title: "TB Admin", topMenuSetting: [{ key: "main", title: "Main" }] };
const nav: navType = {
  menuSet: [
    {
      parentkey: "main",
      menuSetting: [
        { tab: { key: "dashboard", title: "Dashboard", page: <div>Home</div> }, hasPage: true },
      ],
    },
  ],
};

export default function App() {
  return (
    <TbProvider basename="/">
      <TbpProvider>
        <TbFrame setting={setting} top={top} nav={nav} />
      </TbpProvider>
    </TbProvider>
  );
}

6) Usage

기본 사용

import { Tbpage } from "@thefreshop/tb";

const columns = [
  {
    tableProps: { dataIndex: "name", title: "Name" },
    search: true,
    create: true,
    modify: true,
  },
];

export default function Users() {
  return (
    <Tbpage
      title="Users"
      decs="User list"
      searchOption={[{ key: "base", items: [{ type: "input", key: "name", title: "Name" }] }]}
      tableProps={{ rowKey: "id", columns, dataSource: [] }}
    />
  );
}

옵션/설정(핵심 props 요약)

TbFrame

| 이름 | 타입 | 기본값 | 설명 | | --- | --- | --- | --- | | setting | tbframeType | - | 로그인/시작 탭 등 기본 프레임 설정 | | top | topType | - | 상단 영역 설정 | | nav | navType | - | 네비게이션/탭 정의 | | bottom | bottomType | undefined | 하단 영역 | | top_banner | React.ReactNode | undefined | 상단 배너 영역 | | hashmode | boolean | false | 해시 라우팅 사용 여부 | | frameStyle | FrameStyleType | undefined | 스타일 오버라이드 |

Tbpage

| 이름 | 타입 | 기본값 | 설명 | | --- | --- | --- | --- | | tableProps | any | - | AntBaseTable에 전달되는 props | | searchOption | any | undefined | SearchBox 옵션 | | searchDisabled | boolean | false | 검색 비활성화 | | onSubmit | (searchdata?, rowdata?, isReset?) => void | undefined | 검색 제출/리셋 콜백 | | isLoading | boolean | undefined | 로딩 오버레이 | | title/decs | string | undefined | 타이틀/설명 | | PageStyle | PageStyleType | undefined | 스타일 오버라이드 |

더 많은 props 및 타입은 docs/API.md를 참고하세요.

반환값/에러

| 항목 | 반환 | 에러/주의사항 | | --- | --- | --- | | useTbState() | ProviderType | TbProvider 밖에서 호출 시 Error throw |

7) API Reference

API가 많은 관계로 docs/API.md로 분리했습니다.

• 핵심 export: TbProvider, useTbState, tbContext, TbFrame, TbpProvider, ContentLayout, Tbpage, TbpageSm, Tblist, TbpageMulti, AntBaseTable, AntBaseModalCreate, AuthTable 및 타입들

8) TypeScript

• 타입 엔트리: package.json의 types: ./dist/cjs/index.d.ts
• 공개 타입: export type * from "./types"로 노출

import type { tbframeType, navType, antBasePropsType } from "@thefreshop/tb";

9) Compatibility

• Runtime: 브라우저 기반 React 앱 (DOM lib 사용)
• React: react@^19.1.1 (peer)
• Router: react-router@^7.10.0 (peer)
• UI: antd@^6.0.0 (peer)
• CJS/ESM: main(CJS), module(ESM) 빌드 제공
• Node 엔진: Not found in repository

10) Bundling / Tree-shaking

• exports/sideEffects 필드가 없어 트리 셰이킹 동작은 번들러 설정에 의존합니다.
• Rollup 빌드에서 CSS Modules를 런타임 inject 하므로 일부 부수효과(side effects)가 있을 수 있습니다.

11) Examples

Basic (프레임 구성)

import { TbProvider, TbpProvider, TbFrame } from "@thefreshop/tb";
import type { navType, topType, tbframeType } from "@thefreshop/tb";

const setting: tbframeType = { islogin: false };
const top: topType = { title: "Admin", topMenuSetting: [{ key: "main", title: "Main" }] };
const nav: navType = {
  menuSet: [
    {
      parentkey: "main",
      menuSetting: [{ tab: { key: "home", title: "Home", page: <div>Home</div> }, hasPage: true }],
    },
  ],
};

export default function App() {
  return (
    <TbProvider>
      <TbpProvider>
        <TbFrame setting={setting} top={top} nav={nav} />
      </TbpProvider>
    </TbProvider>
  );
}

Advanced (검색 + 테이블)

import { Tbpage } from "@thefreshop/tb";

const columns = [
  { tableProps: { dataIndex: "name", title: "Name" }, search: true, create: true, modify: true },
];

export default function Users() {
  return (
    <Tbpage
      title="Users"
      searchOption={[{ key: "base", items: [{ type: "input", key: "name", title: "Name" }] }]}
      tableProps={{ rowKey: "id", columns, dataSource: [] }}
      onSubmit={(query, data) => {
        console.log(query, data);
      }}
    />
  );
}

Real-world (멀티 패널)

import { TbpageMulti } from "@thefreshop/tb";

export default function Dashboard() {
  return (
    <TbpageMulti
      title="Dashboard"
      arrtableProps={[
        { type: "table", title: "Left", tableprops: { rowKey: "id", columns: [], dataSource: [] } },
        { type: "module", title: "Right", module: <div>Custom Module</div> },
      ]}
      arrflex={[2, 1]}
      direction="row"
    />
  );
}

12) Troubleshooting

1. peerDependencies 충돌: React/antd/react-router 버전이 맞지 않으면 런타임 오류가 발생합니다.
2. CSS Modules 미적용: 소비 앱 번들러에서 CSS Modules가 비활성화되면 레이아웃이 깨집니다.
3. SSR 환경 오류: sessionStorage 사용으로 SSR 시 window 관련 에러가 날 수 있습니다.
4. CJS/ESM 혼용 오류: 번들러가 module/main 선택을 잘못하면 중복 React 경고가 발생할 수 있습니다.
5. 타입 인식 실패: types 경로(dist/cjs/index.d.ts)가 올바르게 배포되었는지 확인하세요.
6. Ant Design 스타일 누락: 소비 앱에서 antd 스타일을 로드하지 않으면 컴포넌트가 깨집니다.
7. 모달 폼 초기값 미반영: AntBaseModalCreate에서 initialValues 사용 시 open 타이밍을 확인하세요.

13) FAQ

1. React 18에서도 동작하나요? Not found in repository (peerDependencies는 React 19 기준입니다).
2. React Router v6 사용 가능? Not found in repository (peerDependencies는 v7 기준입니다).
3. 라우팅 구조는 어떻게 만들나요? nav.menuSet과 nav.globalTabs 기반으로 라우트가 자동 생성됩니다.
4. 해시 라우팅을 지원하나요? TbFrame의 hashmode로 지원합니다.
5. 탭 상태는 어디에 저장되나요? sessionStorage의 tbFrameState 키에 저장됩니다.
6. 로케일 설정은 어디서 하나요? TbpProvider가 antd ConfigProvider와 ko_KR 로케일을 설정합니다.
7. 테스트 예제나 Storybook이 있나요? Not found in repository.
8. 변경 이력(Changelog)이 있나요? No changelog found.

14) Contributing

로컬 개발

yarn install

yarn dev

yarn build

• 테스트/린트 스크립트: Not found in repository
• 배포 스크립트: Not found in repository

15) Security

• 공급망 보안: peerDependencies 버전을 고정/검증하세요.
• 토큰/시크릿 관리: 레포에 환경변수 파일이 없으므로 소비 앱에서 안전하게 관리하세요.
• 취약점 신고: package.json의 bugs.url 참고.

16) License

• package.json: MIT
• LICENSE 파일: No license file found

17) Quick Commands

| 목적 | 명령 | 비고 | | --- | --- | --- | | 개발(와치) | ```bash yarn dev

| 빌드 | ```bash
yarn build
``` | `dist/` 출력 |
| 테스트 | Not found in repository | - |
| 린트 | Not found in repository | - |
| 타입체크 | Not found in repository | - |
| 퍼블리시 | Not found in repository | - |