|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +Shared UI component library (`@rstack-dev/doc-ui`) for Rstack websites (rspack.rs, rsbuild.rs, rspress.rs). |
| 4 | + |
| 5 | +## Tech Stack |
| 6 | + |
| 7 | +- React 18 + TypeScript 5.9 (strict mode) |
| 8 | +- Build: Rslib (based on Rsbuild) |
| 9 | +- Styling: SCSS Modules (`.module.scss`) |
| 10 | +- Animation: Framer Motion, Lottie |
| 11 | +- UI: Ant Design 6 |
| 12 | +- Dev: Storybook 10 |
| 13 | + |
| 14 | +## Commands |
| 15 | + |
| 16 | +```bash |
| 17 | +# Development |
| 18 | +pnpm dev # Start Storybook (port 6006) |
| 19 | + |
| 20 | +# Build |
| 21 | +pnpm build # Build with Rslib |
| 22 | +pnpm build:watch # Watch mode |
| 23 | + |
| 24 | +# Lint (prefer file-scoped) |
| 25 | +pnpm lint # Check all with Biome |
| 26 | +pnpm lint:fix # Auto-fix |
| 27 | + |
| 28 | +# Single file commands |
| 29 | +npx tsc --noEmit 'path/to/file.tsx' |
| 30 | +npx prettier --write 'path/to/file.tsx' |
| 31 | +npx biome check --write 'path/to/file.tsx' |
| 32 | +``` |
| 33 | + |
| 34 | +No test framework - visual testing via Storybook. |
| 35 | + |
| 36 | +## Project Structure |
| 37 | + |
| 38 | +``` |
| 39 | +src/ |
| 40 | +├── announcement/ # Announcement banner |
| 41 | +├── antd/ # Ant Design wrappers |
| 42 | +├── background-image/ # Background component |
| 43 | +├── benchmark/ # Benchmark display |
| 44 | +├── built-with-rspack/ # Showcase component |
| 45 | +├── fully-featured/ # Feature list |
| 46 | +├── hero/ # Hero section |
| 47 | +├── nav-icon/ # Nav icon with popover |
| 48 | +├── section-style/ # Section utilities |
| 49 | +├── tool-stack/ # Tool stack display |
| 50 | +├── why-rspack/ # Feature cards |
| 51 | +├── env.d.ts # Type declarations |
| 52 | +└── shared.tsx # Shared utilities |
| 53 | +
|
| 54 | +stories/ # Storybook stories |
| 55 | +``` |
| 56 | + |
| 57 | +## Code Style |
| 58 | + |
| 59 | +### Formatting (Prettier - `.prettierrc`) |
| 60 | + |
| 61 | +- Single quotes, trailing commas (`all`), no parens for single arrow params |
| 62 | + |
| 63 | +### Linting (Biome - `biome.json`) |
| 64 | + |
| 65 | +- `noExplicitAny`: off, `noArrayIndexKey`: off |
| 66 | +- File naming: `camelCase`, `PascalCase`, or export name |
| 67 | + |
| 68 | +### TypeScript |
| 69 | + |
| 70 | +- Strict mode, use `type` imports: `import type { FC } from 'react'` |
| 71 | +- Path alias: `@/*` → `./src/*` |
| 72 | + |
| 73 | +### Imports Order |
| 74 | + |
| 75 | +1. External packages (react, antd, framer-motion) |
| 76 | +2. Internal components (relative) |
| 77 | +3. Styles (`.module.scss`) |
| 78 | +4. Assets (JSON, images) |
| 79 | + |
| 80 | +```typescript |
| 81 | +import type { FC } from 'react'; |
| 82 | +import { useState } from 'react'; |
| 83 | +import { useInView } from 'react-intersection-observer'; |
| 84 | +import { ProgressBar } from './ProgressBar'; |
| 85 | +import styles from './index.module.scss'; |
| 86 | +``` |
| 87 | + |
| 88 | +## Component Patterns |
| 89 | + |
| 90 | +### Naming |
| 91 | + |
| 92 | +- Components: `PascalCase` (`Hero`, `NavIcon`) |
| 93 | +- Hooks: `useCamelCase` (`useMouseMove`) |
| 94 | +- Props: `ComponentNameProps` (`HeroProps`) |
| 95 | +- Styles: `index.module.scss` per component |
| 96 | + |
| 97 | +### Structure |
| 98 | + |
| 99 | +```typescript |
| 100 | +import type { FC } from 'react'; |
| 101 | +import styles from './index.module.scss'; |
| 102 | + |
| 103 | +export type MyComponentProps = { |
| 104 | + title: string; |
| 105 | + active?: boolean; |
| 106 | +}; |
| 107 | + |
| 108 | +export const MyComponent: FC<MyComponentProps> = ({ |
| 109 | + title, |
| 110 | + active = false, |
| 111 | +}) => { |
| 112 | + return <div className={styles.root}>{title}</div>; |
| 113 | +}; |
| 114 | +``` |
| 115 | + |
| 116 | +### Styling |
| 117 | + |
| 118 | +- SCSS Modules only (`.module.scss`) |
| 119 | +- Compose: `${styles.btn} ${styles.btnPrimary}` |
| 120 | +- Root class: `styles.root` |
| 121 | + |
| 122 | +## Do / Don't |
| 123 | + |
| 124 | +### Do |
| 125 | + |
| 126 | +- Functional components with hooks |
| 127 | +- SCSS Modules for styling |
| 128 | +- Export types with components |
| 129 | +- Semantic HTML (`section`, `button`) |
| 130 | +- Default values for optional props |
| 131 | +- `memo()` for expensive components |
| 132 | + |
| 133 | +### Don't |
| 134 | + |
| 135 | +- Inline styles (except dynamic values) |
| 136 | +- CSS-in-JS (emotion, styled-components) |
| 137 | +- Hard-coded colors |
| 138 | +- Class components |
| 139 | +- Heavy deps without consideration |
| 140 | + |
| 141 | +## Storybook |
| 142 | + |
| 143 | +```typescript |
| 144 | +// stories/Hero.stories.tsx |
| 145 | +import { Hero } from '@rstack-dev/doc-ui/hero'; |
| 146 | +import './index.scss'; |
| 147 | + |
| 148 | +export const HeroStory = () => <Hero onClickGetStarted={() => {}} />; |
| 149 | + |
| 150 | +export default { title: 'Hero' }; |
| 151 | +``` |
| 152 | + |
| 153 | +## Git Hooks |
| 154 | + |
| 155 | +Pre-commit via `simple-git-hooks` + `nano-staged`: |
| 156 | + |
| 157 | +- Biome lint on JS/TS |
| 158 | +- Prettier format on all files |
| 159 | + |
| 160 | +## Adding Components |
| 161 | + |
| 162 | +1. Create `src/component-name/index.tsx` |
| 163 | +2. Add `src/component-name/index.module.scss` |
| 164 | +3. Add entry in `rslib.config.ts` |
| 165 | +4. Add export in `package.json` exports |
| 166 | +5. Create `stories/ComponentName.stories.tsx` |
| 167 | + |
| 168 | +## External Dependencies |
| 169 | + |
| 170 | +Externalized (consumers provide): `react`, `react-dom`, `framer-motion` |
| 171 | + |
| 172 | +Peer deps: `antd`, `lottie-web`, `react-intersection-observer` |
0 commit comments