@restnfeel/agentc-starter-kit

# Development Guide Guide for developers who want to contribute to or extend AgentC Starter Kit. ## Getting Started ### Prerequisites - Node.js 18+ - npm/yarn/pnpm - Git ### Local Setup 1. Clone the repository: ```bash git clone https://github.com/agentc/starter-kit.git cd starter-kit ``` 2. Install dependencies: ```bash npm install ``` 3. Start development: ```bash npm run dev ``` 4. Build the library: ```bash npm run build ``` ## Project Structure ``` agentc-starter-kit/ ├── src/ │ ├── components/ # Component source code │ │ ├── ui/ # Basic UI components │ │ ├── sections/ # Landing page sections │ │ ├── auth/ # Authentication components │ │ ├── dashboard/ # Dashboard components │ │ ├── legal/ # Legal compliance components │ │ └── layout/ # Layout components │ ├── hooks/ # Custom React hooks │ ├── utils/ # Utility functions │ ├── types/ # TypeScript type definitions │ └── index.ts # Main export file ├── dist/ # Built files (generated) ├── docs/ # Documentation ├── examples/ # Usage examples ├── scripts/ # Build scripts └── tests/ # Test files ``` ## Development Workflow ### 1. Adding New Components When adding a new component: 1. Create the component file in the appropriate directory 2. Export it from the directory's `index.ts` 3. Add it to the main `src/index.ts` 4. Create TypeScript interfaces 5. Add documentation 6. Write tests 7. Update examples Example component structure: ```tsx // src/components/ui/NewComponent.tsx import React from "react"; import { cn } from "../../utils/cn"; export interface NewComponentProps { children?: React.ReactNode; variant?: "default" | "primary"; className?: string; } export const NewComponent: React.FC<NewComponentProps> = ({ children, variant = "default", className, ...props }) => { return ( <div className={cn( "base-styles", variant === "primary" && "primary-styles", className )} {...props} > {children} </div> ); }; ``` ### 2. Component Guidelines #### Naming Conventions - Use PascalCase for component names - Use camelCase for props - Use kebab-case for CSS classes - Prefix interfaces with component name: `ButtonProps` #### Props Design - Always include `className` prop for customization - Use sensible defaults - Support `children` when appropriate - Include `...props` for HTML attributes #### Styling Guidelines - Use Tailwind CSS utility classes - Support dark mode with `dark:` variants - Include hover and focus states - Ensure responsive design - Use the `cn()` utility for conditional classes #### TypeScript - Export prop interfaces - Use generic types when appropriate - Provide proper JSDoc comments - Include examples in documentation ### 3. Testing #### Unit Tests ```bash npm run test npm run test:watch npm run test:coverage ``` #### Component Testing - Test all prop variations - Test keyboard navigation - Test accessibility features - Test responsive behavior Example test: ```tsx import { render, screen } from "@testing-library/react"; import { Button } from "../Button"; describe("Button", () => { it("renders correctly", () => { render(<Button>Click me</Button>); expect(screen.getByRole("button")).toBeInTheDocument(); }); it("applies variant styles", () => { render(<Button variant="primary">Primary</Button>); expect(screen.getByRole("button")).toHaveClass("bg-primary-500"); }); }); ``` ### 4. Documentation #### Component Documentation Each component should have: - Props table with types and descriptions - Usage examples - Accessibility notes - Customization examples #### Code Comments ````tsx /** * A versatile button component with multiple variants and states. * * @example * ```tsx * <Button variant="primary" size="lg"> * Submit * </Button> * ``` */ export const Button: React.FC<ButtonProps> = ({ ... }) => { // Implementation }; ```` ## Build System ### Rollup Configuration The build system uses Rollup with: - TypeScript compilation - CSS processing with PostCSS - Dual ESM/CJS output - Tree shaking support - Type declaration generation ### Build Scripts ```bash # Development build with watching npm run dev # Production build npm run build # Clean build artifacts npm run clean # Type checking only npm run type-check # Lint code npm run lint # Format code npm run format ``` ### Output Structure ``` dist/ ├── index.js # ESM bundle ├── index.cjs # CommonJS bundle ├── index.d.ts # TypeScript declarations └── styles.css # Compiled styles ``` ## Accessibility Guidelines ### WCAG Compliance All components must meet WCAG 2.1 AA standards: - Semantic HTML elements - Proper ARIA attributes - Keyboard navigation support - Color contrast compliance - Screen reader compatibility ### Implementation Checklist - [ ] Semantic HTML structure - [ ] Proper heading hierarchy - [ ] Focus management - [ ] Keyboard navigation - [ ] ARIA labels and descriptions - [ ] Color contrast testing - [ ] Screen reader testing ### Example Implementation ```tsx export const Modal: React.FC<ModalProps> = ({ isOpen, onClose, title, children, }) => { const titleId = useId(); useEffect(() => { if (isOpen) { // Trap focus within modal const focusableElements = modal.querySelectorAll( 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])' ); // Implementation... } }, [isOpen]); return ( <div role="dialog" aria-modal="true" aria-labelledby={titleId} className={cn("fixed inset-0 z-50", isOpen ? "block" : "hidden")} > <h2 id={titleId}>{title}</h2> {children} </div> ); }; ``` ## Performance Optimization ### Bundle Size - Tree shaking support - Individual component imports - Minimal dependencies - Code splitting ready ### Runtime Performance - Memoization where appropriate - Efficient re-renders - Lazy loading support - Optimized animations ### Example Optimization ```tsx import { memo, useMemo } from "react"; export const ExpensiveComponent = memo<ExpensiveComponentProps>( ({ data, onSelect }) => { const processedData = useMemo(() => { return expensiveDataProcessing(data); }, [data]); return ( <div> {processedData.map((item) => ( <Item key={item.id} data={item} onClick={onSelect} /> ))} </div> ); } ); ``` ## Release Process ### Version Management We use semantic versioning (semver): - `MAJOR.MINOR.PATCH` - Breaking changes increment MAJOR - New features increment MINOR - Bug fixes increment PATCH ### Release Steps 1. Update version in `package.json` 2. Update CHANGELOG.md 3. Run tests and build 4. Create git tag 5. Push to repository 6. Publish to npm ```bash # Prepare release npm version patch # or minor/major npm run build npm test # Publish npm publish # Push tags git push --tags ``` ### Changelog Format ```markdown ## [1.2.0] - 2024-01-15 ### Added - New DataTable component with sorting and pagination - Dark mode support for all components ### Changed - Updated Button component API - Improved accessibility for Modal component ### Fixed - Fixed focus trap in Modal component - Resolved TypeScript errors in build ### Breaking Changes - Removed deprecated `size` prop from Card component ``` ## Contributing Guidelines ### Code Style - Use TypeScript - Follow ESLint configuration - Use Prettier for formatting - Write meaningful commit messages ### Commit Convention ``` type(scope): description Types: feat, fix, docs, style, refactor, test, chore Scope: component name or area Examples: feat(button): add loading state fix(modal): resolve focus trap issue docs(readme): update installation guide ``` ### Pull Request Process 1. Fork repository 2. Create feature branch 3. Make changes with tests 4. Update documentation 5. Submit pull request 6. Address review feedback ### Issue Reporting When reporting issues: - Use provided templates - Include reproduction steps - Specify environment details - Add relevant screenshots/videos ## Debugging ### Common Issues #### Build Errors ```bash # Clear build cache npm run clean # Reinstall dependencies rm -rf node_modules package-lock.json npm install # Check TypeScript errors npm run type-check ``` #### Style Issues ```bash # Rebuild styles npm run build:css # Check Tailwind config npx tailwindcss --init --dry-run ``` #### Import Errors - Check export statements in index files - Verify TypeScript declarations - Ensure proper file extensions ### Development Tools - React DevTools - TypeScript Language Server - ESLint extension - Prettier extension - Tailwind CSS IntelliSense ## Resources ### Documentation - [React Documentation](https://react.dev) - [TypeScript Handbook](https://www.typescriptlang.org/docs/) - [Tailwind CSS Docs](https://tailwindcss.com/docs) - [WCAG Guidelines](https://www.w3.org/WAI/WCAG21/quickref/) ### Tools - [Rollup](https://rollupjs.org/) - [Jest](https://jestjs.io/) - [Testing Library](https://testing-library.com/) - [Storybook](https://storybook.js.org/) ### Community - [GitHub Discussions](https://github.com/agentc/starter-kit/discussions) - [Discord Server](https://discord.gg/agentc) - [Twitter](https://twitter.com/agentc_dev)