Maofeng
92 lines
3.6 KiB
Plaintext
92 lines
3.6 KiB
Plaintext
---
|
|
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.
|