Dashboard library: grid layout, panels, widgets, app shell
npm install dashboardity
├── src/ # 라이브러리 소스
│ ├── core/ # 대시보드 엔진 (레이아웃, 스펙 해석, JSON → 렌더링)
│ ├── widget-wrapper/ # Widget 공통 래퍼 (header, padding, error, empty)
│ ├── app-shell/ # TopBar, SideNav, DashboardPicker, TimeRangePicker
│ ├── data-adapter/ # API → 위젯 입력 포맷 변환
│ └── shared/ # types, utils, theme
├── examples/
│ └── playground/ # 위젯/대시보드 테스트용 앱
└── package.json
`
위젯 (사용자 정의)
기본 위젯은 내장하지 않습니다. WidgetDefinition / WidgetProps 타입에 맞춰 위젯을 만들고 createWidgetRegistry로 등록해 사용합니다.
`ts
import { createWidgetRegistry, type WidgetDefinition } from "dashboardity";
// 자체 위젯 정의 후
const widgetRegistry = createWidgetRegistry({
stat: MyStatWidget,
text: MyTextWidget,
});
`
App shell / 커스텀 픽커
TopBar에 dashboardPicker, timeRangePicker 슬롯이 있습니다. 기본 제공 컴포넌트를 쓰거나, 자기 걸 넣을 수 있습니다.
`tsx
import { TopBar, DashboardPicker, TimeRangePicker } from "dashboardity";
// 기본 픽커 사용
title="My App"
dashboardPicker={ }
timeRangePicker={ }
/>
// 커스텀 픽커 사용 (같은 props 타입 사용 가능: DashboardPickerProps, TimeRangePickerProps)
title="My App"
dashboardPicker={ }
timeRangePicker={ }
/>
`
dashboardPicker / timeRangePicker를 넘기지 않으면 해당 슬롯은 비고, children으로만 우측 영역을 채울 수 있습니다.
시작하기
$3
- Node 18+
$3
- @dashboardity/layout-core, @dashboardity/layout-store, react-griditty — npm ^1.0.0 사용.
로컬 개발만 할 때: npm에 아직 안 올렸다면 npm overrides 또는 로컬 file: 로 임시 지정 가능.
$3
`bash
npm install
npm run build # 라이브러리 빌드
npm run example # playground 앱 실행
`
$3
- npm run build — 라이브러리 빌드 (tsup)
- npm run dev — 라이브러리 watch 빌드
- npm run example — playground 앱 실행 (Vite)
- npm run clean — dist 삭제
$3
이전에 pnpm을 쓰던 폴더이거나 캐시 문제일 수 있습니다. 프로젝트 루트에서 순서대로 시도하세요.
`bash
1) node_modules·lock 삭제
rmdir /s /q node_modules
del package-lock.json
2) npm 캐시 정리
npm cache clean --force
3) npm 최신으로 업데이트 (선택)
npm install -g npm@latest
4) 다시 설치
npm install
`
PowerShell: node_modules 삭제는 Remove-Item -Recurse -Force node_modules, lock 삭제는 Remove-Item package-lock.json -ErrorAction SilentlyContinue
배포 (npm + Git)
1. Git
- package.json의 repository.url에 실제 저장소 URL 넣기 (예: "url": "https://github.com/사용자/react-dashitty.git").
- git add . → git commit → git remote add origin ... → git push -u origin main (또는 기본 브랜치 이름).
2. npm
- npmjs.com 로그인: 터미널에서 npm login.
- 패키지 이름이 이미 쓰였으면 package.json의 name을 바꾸거나 스코프 사용 (예: @내계정/dashboardity).
- npm run build 후 npm publish. (prepublishOnly로 publish 시 자동 빌드됨.)
- 비공개 패키지가 아니면 스코프 패키지 첫 배포 시: npm publish --access public.
dist/는 .gitignore에 있어서 Git에는 안 올라가고, npm publish 시에만 files: ["dist"]로 포함됩니다.
스펙 → 렌더링
대시보드는 JSON 스펙으로 정의됩니다.
`ts
DashboardSpec
└─ panels[]
└─ widgets[] // type + options + dataSourceId
layout.items[] // grid 좌표 (layout-store)
`
Grid 계산은 @dashboardity/layout-core / @dashboardity/layout-store`를 사용하며, 위젯은 width/height만 신경 쓰면 됩니다.