Skip to content

AGENTS.md

Latest commit

 

History

History
171 lines (124 loc) · 4.2 KB

AGENTS.md

File metadata and controls

171 lines (124 loc) · 4.2 KB
Raw

AGENTS.md

Shared UI component library (@rstackjs/doc-ui) for Rstack websites (rspack.rs, rsbuild.rs, rspress.rs).

Tech Stack

  • React 19 + TypeScript 7 (strict mode)
  • Toolchain: Rstack CLI (rs lib, Rstest, Rslint, and formatting)
  • Styling: SCSS Modules (.module.scss)
  • Animation: Framer Motion, Lottie
  • UI: Ant Design 6
  • Dev: Storybook 10

For Rstack CLI behavior:

  • Read the docs linked from node_modules/rstack/docs/llms.txt when needed
  • Online docs: https://rstack.rs/llms.txt
  • Run rs -h for CLI help

Commands

# Development
pnpm dev              # Start Storybook (port 6006)

# Build and test
pnpm build            # Build the library with Rstack CLI
pnpm build:watch      # Build in watch mode
pnpm test             # Run Rstest

# Checks and formatting
pnpm check            # Run lint and formatting checks
pnpm lint             # Run Rslint
pnpm format           # Format files

Project Structure

src/
├── announcement/       # Announcement banner
├── antd/               # Ant Design wrappers
├── background-image/   # Background component
├── benchmark/          # Benchmark display
├── built-with-rspack/  # Showcase component
├── fully-featured/     # Feature list
├── hero/               # Hero section
├── nav-icon/           # Nav icon with popover
├── section-style/      # Section utilities
├── tool-stack/         # Tool stack display
├── why-rspack/         # Feature cards
├── env.d.ts            # Type declarations
└── shared.tsx          # Shared utilities

stories/                # Storybook stories

Code Style

Formatting (define.fmt in rstack.config.ts)

  • Single quotes, trailing commas (all), no parens for single arrow params

Linting (define.lint in rstack.config.ts)

  • Rslint uses TypeScript and React recommended rules
  • @typescript-eslint/no-explicit-any: off
  • react/react-in-jsx-scope: off

TypeScript

  • Strict mode, use type imports: import type { FC } from 'react'
  • Path alias: @/* → ./src/*

Imports Order

  1. External packages (react, antd, framer-motion)
  2. Internal components (relative)
  3. Styles (.module.scss)
  4. Assets (JSON, images)
import type { FC } from 'react';
import { useState } from 'react';
import { useInView } from 'react-intersection-observer';
import { ProgressBar } from './ProgressBar';
import styles from './index.module.scss';

Component Patterns

Naming

  • Components: PascalCase (Hero, NavIcon)
  • Hooks: useCamelCase (useMouseMove)
  • Props: ComponentNameProps (HeroProps)
  • Styles: index.module.scss per component

Structure

import type { FC } from 'react';
import styles from './index.module.scss';

export type MyComponentProps = {
  title: string;
  active?: boolean;
};

export const MyComponent: FC<MyComponentProps> = ({
  title,
  active = false,
}) => {
  return <div className={styles.root}>{title}</div>;
};

Styling

  • SCSS Modules only (.module.scss)
  • Compose: ${styles.btn} ${styles.btnPrimary}
  • Root class: styles.root

Do / Don't

Do

  • Functional components with hooks
  • SCSS Modules for styling
  • Export types with components
  • Semantic HTML (section, button)
  • Default values for optional props
  • memo() for expensive components

Don't

  • Inline styles (except dynamic values)
  • CSS-in-JS (emotion, styled-components)
  • Hard-coded colors
  • Class components
  • Heavy deps without consideration

Storybook

// stories/Hero.stories.tsx
import { Hero } from '@rstackjs/doc-ui/hero';
import './index.scss';

export const HeroStory = () => <Hero onClickGetStarted={() => {}} />;

export default { title: 'Hero' };

Git Hooks

Rstack CLI installs repository hooks from .rstack/hooks. The pre-commit hook runs rs staged.

Adding Components

  1. Create src/component-name/index.tsx
  2. Add src/component-name/index.module.scss
  3. Add an entry in rstack.config.ts
  4. Add an export in package.json exports
  5. Create stories/ComponentName.stories.tsx

External Dependencies

Externalized (consumers provide): react, react-dom, framer-motion

Peer deps: antd, lottie-web, react-intersection-observer