556
Bn
bees-nest / files
bees-nest / AGENTS.md
4.7 KB
1# AGENTS.md 2 3This file provides guidance for AI coding agents working in the bees-nest codebase. 4 5## Project Overview 6 7**bees-nest** is a search engine application with: 8- **Search UI**: User-facing search interface 9- **API**: Backend search and indexing endpoints 10- **Database**: Storage for indexed content 11- **Web Crawler**: Distributed crawling component, opt-in by users 12 13Built with Next.js 16, React 19, Tailwind CSS v4, and shadcn/ui components. 14 15## Build & Development Commands 16 17```bash 18# Package manager: Bun 19bun install # Install dependencies 20bun run dev # Start Next.js dev server 21bun run build # Production build 22bun run start # Start production server 23bun run lint # Run linter (biome check) 24bun run format # Format code (biome format --write) 25``` 26 27## Testing 28 29**No test framework is currently configured.** If tests are added, update this section. 30 31## Project Structure 32 33``` 34src/ 35 app/ # Next.js App Router pages 36 globals.css # Global styles, Tailwind imports, theme variables 37 layout.tsx # Root layout 38 page.tsx # Home page 39 components/ 40 ui/ # Reusable UI components (shadcn/radix-maia style) 41 *.tsx # Feature/example components 42 lib/ 43 utils.ts # Utility functions (cn helper) 44``` 45 46Note: As the project grows, expect additional directories for API routes, database 47models, crawler logic, and search functionality. 48 49## Code Style Guidelines 50 51### TypeScript 52 53- Strict mode enabled (`tsconfig.json`) 54- Use `React.ComponentProps<"element">` for extending native element props 55- Use intersection types for additional props 56- Always provide explicit types for function parameters and return values 57 58### File Naming 59 60- **Component files**: kebab-case (`alert-dialog.tsx`, `input-group.tsx`) 61- **Component names**: PascalCase (`AlertDialog`, `InputGroup`) 62- **Utility functions**: camelCase (`cn`, `twMerge`) 63 64### Import Organization 65 66Biome automatically organizes imports. Follow this order: 671. React imports: `import * as React from "react"` 682. External libraries (radix-ui, @base-ui/react, etc.) 693. Internal imports using `@/` path alias 70 71```typescript 72"use client" 73 74import * as React from "react" 75import { AlertDialog as AlertDialogPrimitive } from "radix-ui" 76 77import { cn } from "@/lib/utils" 78import { Button } from "@/components/ui/button" 79``` 80 81### Component Patterns 82 83**Function declarations** (not arrow functions) for components: 84 85```typescript 86function Button({ 87 className, 88 variant = "default", 89 size = "default", 90 ...props 91}: React.ComponentProps<"button"> & ButtonProps) { 92 return ( 93 <button 94 data-slot="button" 95 data-variant={variant} 96 className={cn(buttonVariants({ variant, size, className }))} 97 {...props} 98 /> 99 ) 100} 101``` 102 103**Required patterns:** 104- Add `data-slot="component-name"` to root elements for styling/targeting 105- Add `data-*` attributes for variants and state (`data-variant`, `data-size`) 106- Spread `{...props}` last on elements 107- Use `cn()` utility for conditional class composition 108- Use default parameter values in destructuring 109- Export both component and variants: `export { Button, buttonVariants }` 110 111### Styling 112 113- **Tailwind CSS v4** with custom theme in `globals.css` 114- **CVA (class-variance-authority)** for variant management 115- **oklch color format** for theme colors 116- **`rounded-4xl`** as standard border radius 117- Dark mode via `.dark` class 118 119### Icons 120 121Use **Hugeicons**: `<HugeiconsIcon icon={ArrowDown01Icon} strokeWidth={2} className="size-4" />` 122Import from `@hugeicons/react` and `@hugeicons/core-free-icons`. 123 124### Client Components 125 126Add `"use client"` directive at the top of interactive components (forms, dialogs, 127components using hooks or browser APIs). 128 129### UI Libraries 130 131- **Radix UI**: Import from `radix-ui` package 132- **Base UI**: Import from `@base-ui/react` package 133- Follow shadcn/ui patterns for component structure 134 135### Formatting Rules (Biome) 136 137- Indent: 2 spaces 138- Import organization is automatic 139 140### Error Handling 141 142- Use TypeScript strict mode to catch type errors at compile time 143- Components should handle undefined/null props gracefully via defaults 144 145### Path Aliases 146 147Use `@/` alias for imports from `src/` (e.g., `import { cn } from "@/lib/utils"`). 148 149## Common Tasks 150 151### Adding a New UI Component 152 1531. Create file in `src/components/ui/` with kebab-case name 1542. Add `"use client"` if component is interactive 1553. Import React and relevant primitives 1564. Define variants with CVA if needed 1575. Create component with function declaration 1586. Add `data-slot` attribute to root element 1597. Export component and variants 160 161### Running Checks Before Commit 162 163```bash 164bun run lint && bun run build 165```