xonecas.io
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```