shadcndashboard/shadcndashboard instruction manual

1. Purpose, scope, and Claude Code classification

Shadcn Dashboard instruction manual

**Repository:** `shadcndashboard/shadcndashboard` **Project:** Shadcn Dashboard Free, version `1.0.0` in `package.json` **License:** MIT in the supplied metadata and README

Shadcn Dashboard is a client-side admin-dashboard starter built with React 19, Vite, TypeScript, Tailwind CSS v4, shadcn-style components, and Base UI. It supplies reusable dashboard layouts, application screens, authentication screens, forms, tables, charts, profile views, and other interface components. It is a single-page application (SPA), not a full-stack product: the first-party agent guide explicitly says that this repository has no backend and that its API behavior is mocked with Mock Service Worker (MSW) and static data.

**Claude Code classification: context injection, project-local.** The repository contains `.claude/skills/shadcn-dashboard-free/SKILL.md`, which gives Claude Code project-specific guidance for pages, routes, mock data, tables, forms, charts, icons, navigation, and themes. An equivalent skill also appears under `.agents/skills/`. This is reliable evidence of a local skill that injects repository conventions into an AI coding session. There is no supplied evidence that this is a Claude Code marketplace plugin, MCP server, hook, model gateway, or separate GUI. It should therefore be understood as an ordinary React application that includes a project-local Claude Code skill, rather than as a standalone Claude extension product.

2. Prerequisites, installation, development, and production scripts

The documented prerequisites are **Node.js 18, 20, or 22+** and **npm**. The repository uses `package-lock.json` as its lockfile of record. No pnpm, Yarn, or Bun workflow is documented, so use only npm commands.

From an existing local checkout of the repository, install its dependencies:

npm install

Start the Vite development server:

npm run dev

The documented development address is `http://localhost:5173`. Vite provides hot reload while the server runs.

Create the production build with:

npm run build

The `build` script is exactly `tsc && vite build`. TypeScript checks therefore run first, and a type error stops the production build. A successful build produces the static application output described by the agent guide as `dist/`.

Preview that production build locally:

npm run preview

Check the source with ESLint:

npm run lint

The lint script scans `.ts` and `.tsx` files, reports unused disable directives, and sets `--max-warnings 0`; warnings are consequently treated as failures. These four scripts—`dev`, `build`, `preview`, and `lint`—are the complete script surface documented in both the README and `package.json`. No test script is supplied. The first-party agent guide recommends a clean lint run and emphasizes that the production build performs whole-project TypeScript checking.

3. Included screens, applications, and user-facing capabilities

The starter’s principal screen is a **modern dashboard** containing statistics, charts, widgets, and overview content. The full dashboard shell combines a sidebar and header and is intended for ordinary authenticated/admin views. Responsive, mobile-first styling and a light/dark theme toggle are documented.

Three sample applications are included. **Blog** provides blog-related views and uses a TipTap rich-text editor. **Notes** supplies note-management views. **Tickets** supplies ticket-management views. These are demonstration applications backed by mocked data rather than a server. Their feature state is organized through dedicated blog, notes, and ticket contexts.

The authentication area includes Login, Register, Forgot Password, OTP Verification, Reset Password, Two-Step/Two-Factor Verification, Error, and Maintenance pages. These screens demonstrate flows and layouts; the supplied documentation does not claim that they connect to a real identity service.

General pages include a user profile with connections and activity views, vertical and horizontal form layouts, form-validation demonstrations, and data-table views. The component set includes shadcn-style UI primitives, TanStack Table wrappers, Recharts visualizations, date pickers and calendar controls, a file dropzone, OTP input, loading spinners, an icon showcase, and TipTap editor components. The README also describes reusable blocks for dashboards, charts, tables, forms, and complete apps.

The React demo is available at <https://shadcndashboard-demo.vercel.app>. A separately maintained Next.js free version is linked at <https://github.com/shadcndashboard/next-shadcn-dashboard>; it is not the codebase covered by this manual.

4. Application architecture and where files belong

`src/main.tsx` is the Vite entry point, and `src/App.tsx` is the root application component. Central route configuration lives in `src/routes/Router.tsx`. Page-level screens belong in `src/views/`, divided among `apps/`, `auth/`, `dashboards/`, `icons/`, `pages/`, and `spinner/`. Dashboard pages use layouts under `src/layouts/full/`; auth, error, maintenance, and other bare screens use `src/layouts/blank/`.

Reusable components live under `src/components/`. Put low-level shadcn-style primitives in `src/components/ui/`, feature-specific components in a corresponding domain folder, table wrappers in `src/components/tables/`, form examples in `src/components/form/`, dashboard widgets in `src/components/dashboards/`, and cross-cutting pieces in `src/components/shared/`. The documented convention is to compose primitives in feature components instead of changing a primitive unless the desired behavior should apply globally.

Application data support is under `src/api/`: feature data files hold static records, `src/api/mocks/` configures MSW, and `src/api/global-fetcher.ts` provides shared fetchers. Domain providers belong in `src/context/`; dark/light theme state is under `src/context/shadcntheme/`. Shared TypeScript declarations belong in `src/types/`, reusable hooks in `src/hooks/`, common helpers such as `cn()` in `src/lib/utils.ts`, and global or component CSS in `src/css/`.

Static assets are served from `public/`; local images and SVG helpers may live in `src/assets/`. `components.json` contains shadcn aliases and registry configuration, while Vite, TypeScript, PostCSS, and HTML entry configuration reside in their named root files.

5. Adding pages, routes, sidebar links, and complete features

For a new page, first create its view beneath `src/views/<area>/<page>/index.tsx` or follow the closest sibling folder’s established naming. In `src/routes/Router.tsx`, lazily import the page with React’s `lazy()` and wrap it with the existing `Loadable` component from `src/layouts/full/shared/loadable/Loadable.tsx`. This wrapper supplies the suspense fallback. Add the resulting route beneath `FullLayout` for dashboard content or `BlankLayout` for authentication, errors, maintenance, and other standalone screens.

If users should reach the page through the dashboard sidebar, add its navigation entry using the existing structure under `src/layouts/full/vertical/sidebar/`. The supplied files describe this location and workflow but do not provide a generic copy-paste route or navigation object, so inspect neighboring entries rather than introducing an undocumented shape.

A complete data-backed feature follows six documented stages:

1. Put static data in `src/api/<name>/<name>-data.ts`.
2. Add its MSW request handler and register that handler in `src/api/mocks/handlers/mock-handlers.ts`.
3. Create `src/context/<name>-context/`, fetching through SWR and the shared fetchers while exposing feature state and setters.
4. Build the screen in `src/views/apps/<name>/` or the appropriate `views/` area, composing domain components and `src/components/ui/` primitives.
5. Register the lazy, `Loadable`-wrapped page in `Router.tsx` under the suitable layout.
6. Add a sidebar item when navigation requires one.

Blog, notes, and tickets are the documented reference patterns. Because this repository has no backend, new local demo features should mirror that mock-data pipeline unless an endpoint already exists.

6. Data access, tables, forms, charts, icons, styling, and themes

The application’s data path is **static feature data → MSW handler → shared fetcher/SWR → feature context → view components**. `src/api/global-fetcher.ts` documents `getFetcher`, `postFetcher`, and `putFetcher` for GET, POST, and PUT-style mocked interactions. Feature contexts wrap SWR access and expose data and setters to their consumers. This arrangement simulates application behavior in the browser; it does not create server persistence.

For tabular interfaces, use the wrappers in `src/components/tables/`, such as `DataTable.tsx`, which are built on `@tanstack/react-table`. The documented convention is not to create a separate table implementation from scratch. For charts, use Recharts through `src/components/ui/chart.tsx`; `src/components/dashboards/modern/total-sales.tsx` is a cited example.

No form-management library is currently wired into the project. The documented reference is `src/components/form/index.tsx`, using Input, Select, Switch, Checkbox, RadioGroup, Calendar, and related primitives from `src/components/ui/`. Adding a form library would add a dependency, so the project guidance says to discuss that need first.

The two supported icon packages are `lucide-react` and `@iconify/react`. Match the package already used by the file being changed. The documented Iconify import is:

import { Icon } from '@iconify/react'

Use Tailwind CSS v4 utilities for styling and `cn()` from `src/lib/utils.ts` for conditional or merged classes rather than concatenating class strings. Both `src/*` and `@/*` resolve to `./src/*`; preserve the import style used by nearby code. Theme state and the documented light/dark toggle are provided by the custom theme context under `src/context/shadcntheme/`.

7. Quality checks, deployment model, and operational boundaries

Before treating a frontend change as complete, run the two documented checks:

npm run lint
npm run build

Lint must produce no warnings. The build must pass TypeScript before Vite can bundle the application. Match existing TypeScript types and imports rather than relying on Vite’s development transpilation to expose every problem. The agent guide also advises checking actual source usage before claiming that a dependency represents a working feature.

Deployment output is static. For Netlify, `netlify.toml` redirects all paths to `/index.html`, allowing browser-router URLs to resolve through the SPA. The repository also contains a multi-stage `Dockerfile` and `nginx.conf`; the documented architecture says the image builds with npm and serves through nginx with an SPA fallback. No Docker build or run command is supplied in the first-party text, so this manual does not prescribe one.

Important boundaries follow from the architecture. There are no server actions, server components, API routes, database services, or real backend endpoints in this repository. Authentication pages are interface examples, and Blog, Notes, and Tickets use mock handlers and static data. The README calls the starter production-ready, but deployment of a real product still requires replacing or integrating mocked behavior as appropriate; no replacement procedure is documented here.

The supplied files also contain no automated test command. Available validation consists of ESLint, whole-project TypeScript checking, and the Vite production build. External libraries and services remain governed by their own documentation and versions.

8. Using the local Claude skill, attribution, and support resources

When Claude Code works inside this repository, the project-local skill at `.claude/skills/shadcn-dashboard-free/SKILL.md` provides concise routing guidance for requests involving new views, mock APIs, data tables, forms, routes, sidebar configuration, charts, icons, or dark/light theming. Its conventions mirror `AGENTS.md`: use lazy routes wrapped in `Loadable`, keep backend-like behavior in MSW mocks, reuse table and chart wrappers, preserve local icon/import styles, use `cn()`, and validate with build and lint. The `.agents/skills/` copy provides the same guidance for compatible agent setups. No separate installation command is documented because these files are already part of the repository.

Repository metadata identifies the project as public and MIT-licensed. The README says free items may be used for personal and commercial purposes and asks users to include attribution. Its supplied copy-paste footer link is:

<a href="https://shadcndashboard.dev/">Shadcn Dashboard</a>

Consult the repository’s `LICENSE` for the controlling license terms; the README links it directly. Release information is documented in `CHANGELOG.md`.

First-party project resources include the main site at <https://shadcndashboard.dev>, documentation at <https://shadcndashboard.dev/docs>, and the React demo at <https://shadcndashboard-demo.vercel.app/>. Community links in the README include X/Twitter at <https://x.com/shadcndashboard> and Discord at <https://discord.com/invite/eMzE8F6Wqs>. The repository credits shadcn/ui, Tailwind CSS, Vite, Base UI, TanStack Table, Recharts, and TipTap as foundational projects.