simple-react-app-kit/packages/ui/docs/en-US/guide/setup.mdx

---
title: Project setup
description: Configure the workspace dependency, global styles, Tailwind scanning, and the shadcn CLI.
order: 10
toc:
  - id: dependency
    title: Add the dependency
  - id: global-styles
    title: Global styles
  - id: imports
    title: Explicit imports
  - id: shadcn-cli
    title: shadcn CLI
  - id: browser-components
    title: Browser components
  - id: verify
    title: Verify the setup
---

## Add the dependency {#dependency}

Applications reference the UI package through the workspace protocol:

```json
{
  "dependencies": {
    "@workspace/ui": "workspace:*"
  }
}
```

The applications in this repository are already configured this way. The package is currently private to the workspace and does not need to be installed from npm.

## Global styles {#global-styles}

Import the stylesheet once from the application's global CSS:

```css
@import "@workspace/ui/globals.css";
```

This entry loads Tailwind CSS, shadcn's Tailwind extension, animation utilities, the Inter Variable font, semantic colors, radius variables, and base styles. Themes switch through `.ui:light` and `.ui:dark` on the root element; component code should not copy these variables.

The `@source` directives in `globals.css` cover this repository's `apps` and component directories. Update those paths if the package moves into another directory layout, or production builds may omit utilities used by components.

## Explicit imports {#imports}

There is no aggregated barrel. Import concrete subpaths so dependencies remain visible and client bundles do not grow accidentally:

```tsx
import { Button } from "@workspace/ui/components/button"
import { SaveIcon } from "@workspace/ui/components/icon"
import { useIsMobile } from "@workspace/ui/hooks/use-breakpoint"
import { cn } from "@workspace/ui/lib/utils"
```

Public entry points include:

- `@workspace/ui/components/*` for components and their local types.
- `@workspace/ui/hooks/*` for breakpoint and ripple interactions.
- `@workspace/ui/locales` for supported locales and message ID types.
- `@workspace/ui/locales/en-US` and `@workspace/ui/locales/zh-Hans` for messages and calendar locales.
- `@workspace/ui/globals.css` for global styles.

## shadcn CLI {#shadcn-cli}

Run the command from the repository root:

```sh
bunx shadcn@latest add button -c apps/web
```

The application and UI package `components.json` files agree on `base-vega`, neutral, CSS variables, the Lucide vocabulary, and RTL output. Their aliases place generated files under `packages/ui/src/components`, following shadcn's official [monorepo workflow](https://ui.shadcn.com/docs/monorepo).

Always inspect the diff after generation. The generator does not know about this workspace's Icones layer, localization, ripple behavior, or Popover extensions and can overwrite them when updating an existing component. See the official [`components.json` reference](https://ui.shadcn.com/docs/components-json) for the meaning of each setting.

## Browser components {#browser-components}

Most interactive components depend on events, portals, or browser APIs. Consumers using React Server Components should import them from their own client boundary. This workspace has `rsc: false`; component files do not receive a framework-specific directive globally, although a few components include `"use client"` when they require it.

## Verify the setup {#verify}

After changing a component or configuration, run:

```sh
bun run --cwd packages/ui typecheck
bun run lint
bun run format:check
```

When a change affects consumption, also build the application or docs so Tailwind scanning is exercised, then verify light, dark, and RTL modes.