@sito/dashboard-app

@sito/dashboard-app is a React 19 component and utilities library for building Sito-style admin dashboards, CRUD screens, and internal tools. It packages UI components, hooks, providers, typed API helpers, and styles in a single npm package.

Documentation scope and source of truth

| Document | Primary audience | Source of truth for | | ------------------------------------ | ----------------------------- | --------------------------------------------------------- | | README.md (this file) | Consumer apps and maintainers | Install, requirements, scripts, doc index | | AGENTS.md | AI agents and maintainers | Implementation rules and reference tables | | docs/CONSUMER_GUIDE.md | Consumer apps | Providers, components, props, hooks, API clients | | docs/RECIPES.md (+ split files) | Consumer apps | Index of themed recipe files (layout/data/forms) | | docs/RECIPES_LAYOUT.md | Consumer apps | Providers, app/auth shells, fallback views, PWA, drawer | | docs/RECIPES_DATA.md | Consumer apps | CRUD, entity clients, exports | | docs/RECIPES_FORMS.md | Consumer apps | Forms, dialogs, tabs/onboarding, feedback, auth, errors | | docs/THEME_AND_CSS.md | Consumer apps | CSS tokens, theme variables, safe overrides | | docs/TROUBLESHOOTING.md | Consumer apps | Common provider/typing/styling/auth/routing issues | | docs/ARCHITECTURE_RULES.md | Maintainers | Internal layering and folder rules | | docs/TRANSLATIONS_DASHBOARD_APP.md | Consumer apps | i18n keys required by the library | | .sito/*.md | Internal team and agents | Upstream @sito/dashboard reference (not canonical here) |

Important:

• @sito/dashboard-app is not SSR-compatible. Browser-only.
• For auth-enabled apps, use ConfigProvider -> ManagerProvider -> AuthProvider -> NotificationProvider -> DrawerMenuProvider (NavbarProvider when needed; BottomNavActionProvider optional for dynamic mobile center actions).
• Drawer and Onboarding run without AuthProvider; guest entry is owned by Onboarding.
• IconButton differs by package:
  • @sito/dashboard: icon accepts a React node.
  • @sito/dashboard-app: icon?: IconDefinition (FontAwesome wrapper export).

Installation

npm install @sito/dashboard-app
# or
yarn add @sito/dashboard-app
# or
pnpm add @sito/dashboard-app

Peer dependencies:

npm install \
  [email protected] [email protected] \
  @sito/[email protected] \
  @tanstack/[email protected] \
  [email protected] \
  @fortawesome/[email protected] \
  @fortawesome/[email protected] \
  @fortawesome/[email protected] \
  @fortawesome/[email protected]

Supabase backend (optional):

npm install @supabase/[email protected]

Requirements

• Node.js 22.x (see .nvmrc)
• Browser runtime only (no SSR)
• React 19.2.7
• React DOM 19.2.7
• @tanstack/react-query 5.83.0
• @supabase/supabase-js 2.100.0 (optional)
• react-hook-form 7.61.1
• @sito/dashboard 0.3.0
• Font Awesome peers per package.json

Quick start

1. Wrap your app with providers in canonical order (or use AppProviders / createAppProviders).
2. Extend BaseClient (or SupabaseDataClient) per API resource.
3. Compose pages with AppShell + DashboardHeader + DashboardFooter + Page + dialog/form hooks.

Detailed setup, examples, and prop tables live in:

• Consumer Guide — installation, providers, components, props, hooks, API clients.
• Recipes index — themed copy-ready snippets: layout/providers, data/CRUD/exports, forms/dialogs/UX.
• Theme and CSS — design tokens and safe CSS overrides.
• Troubleshooting — provider/typing/styling/auth/routing diagnostics.
• Translations Reference — required i18n namespaces and keys.

Core exports

• Layout and navigation: Page, Navbar, Drawer, BottomNavigation, TabsLayout, PrettyGrid, ToTop
• Layout shells: AppShell, AuthShell, DashboardHeader, DashboardFooter
• Reusable views: NotFoundView, FeatureUnavailableView
• Actions and menus: Actions, Action, ActionsDropdown, Dropdown, button components
• Dialogs and forms: Dialog, FormDialog, ImportDialog, ExportDialog, PwaUpdateDialog, form inputs
• Feedback: Notification, Loading, Empty, Error, Onboarding, OfflineBanner, TopBanner
• Hooks: useFormDialog, usePostDialog, usePutDialog, useImportDialog, useExportDialog, useDeleteDialog, useMutationForm, useDeleteAction, useNavbar, useOnlineStatus, useOnlineStatusSnapshot, and more — action hooks ship with default sticky, multiple, id, icon, tooltip and now forward className, iconClassName, labelClassName; only onClick is required. Actions renders icon-only items with tooltips by default (showTooltips={true}) and can opt out per action list.
• Providers and utilities: ConfigProvider, ManagerProvider, AppProviders, createAppProviders, SupabaseManagerProvider, AuthProvider, SupabaseAuthProvider, NotificationProvider, DrawerMenuProvider, NavbarProvider, BottomNavActionProvider, useBottomNavAction, useOptionalBottomNavAction, useRegisterBottomNavAction, DTOs, API clients (BaseClient, SupabaseDataClient), useSupabase, filterMenuByFeatureFlags, normalizeMenuDividers.

Local development

git clone https://github.com/sito8943/-sito-dashboard-app.git
cd ./-sito-dashboard-app
nvm use
corepack enable
pnpm install
pnpm run dev
# optional: pnpm run storybook

Scripts

• pnpm run dev — Vite dev server
• pnpm run build — TypeScript + library build
• pnpm run preview — preview built bundle locally
• pnpm run lint — Oxlint type-aware check (no writes)
• pnpm run lint:fix — Oxlint autofix
• pnpm run docs:check — docs policy markers, relative links, version alignment
• pnpm run deps:check — Knip dependency analysis
• pnpm run test — Vitest single run
• pnpm run test:watch — Vitest watch mode
• pnpm run format — Prettier write
• pnpm run format:check — Prettier check
• pnpm run full — lint + format + dependencies + docs + build + tests
• pnpm run storybook — run Storybook locally
• pnpm run build-storybook — static Storybook build

Validation stack

• pnpm run lint
• pnpm run format:check
• pnpm run deps:check
• pnpm run docs:check
• pnpm run test
• pnpm run build
• pnpm run build-storybook
• pnpm pack

Deployment / release

CI:

• .github/workflows/ci.yml — frozen install, full validation, Storybook build, and package-content verification on push / PR

Manual release:

pnpm install --frozen-lockfile
pnpm run full
pnpm run build-storybook
pnpm pack
pnpm publish --access public
git push --follow-tags

Contributing

1. Fork the repo.
2. Branch per feature/fix.
3. Open a PR with change summary + validation notes.

License

MIT (see LICENSE).