main_frontend/AGENTS.md

AGENTS.md — Coffee Project Frontend

Project Overview

Next.js 16 application using Feature-Sliced Design (FSD) architecture, powered by Bun runtime and package manager.

---

Tech Stack

Category	Technology
Runtime	Bun 1.3.5
Framework	Next.js 16.1.1 (App Router)
Language	TypeScript 5.9
UI Library	React 19
Styling	SCSS Modules, normalize.css
State/Fetch	TanStack React Query 5, Axios, Xior
Animation	Framer Motion
Utilities	Lodash, Moment.js, classnames, usehooks-ts
Icons	Lucide React, SVGR (custom icons)
Notifications	React Toastify
File Upload	React Dropzone
Linting	ESLint 9, Prettier, Stylelint
Testing	Jest, Testing Library

---

Commands

bun dev              # Start dev server
bun run build        # Production build
bun run start        # Start production server
bun run lint         # Run ESLint + Prettier
bun run gc <layer> <ComponentName>  # Generate FSD component
bun run gicons       # Convert SVGs to React components

---

Project Structure (FSD)

app/                  # Next.js App Router entry
pages/                # Keep empty (Next.js requires it)
public/               # Static assets
src/
├── app/              # App layer: global styles, providers
├── pages/            # Page compositions
├── widgets/          # Large UI blocks (header, sidebar)
├── features/         # User interactions (auth, search)
├── entities/         # Business entities (user, product)
└── shared/           # Reusable: UI kit, utils, API, assets
    ├── ui/           # Button, Input, Icons...
    ├── api/          # API clients
    ├── lib/          # Utilities
    └── assets/       # Images, raw-icons

Path Aliases

@app/*       → ./src/app/*
@pages/*     → ./src/pages/*
@widgets/*   → ./src/widgets/*
@features/*  → ./src/features/*
@entities/*  → ./src/entities/*
@shared/*    → ./src/shared/*
@/*          → ./src/*

---

Component Structure

Each component follows FSD slice structure:

ComponentName/
├── index.ts              # Public API (re-export)
├── ui/
│   ├── ComponentName.tsx
│   └── ComponentName.module.scss
├── model/
│   └── ComponentName.d.ts  # Props interface
└── api/                  # Optional: component-specific API

Component Template

import type { JSX } from "react"

import { FunctionComponent } from "react"

import { IComponentNameProps } from "../model/ComponentName.d"
import styles from "./ComponentName.module.scss"

export const ComponentName: FunctionComponent<
	IComponentNameProps
> = (): JSX.Element => {
	return (
		<div className={styles.root} data-testid="ComponentName">
			ComponentName
		</div>
	)
}

Generate Component

Use one of these commands to generate new project-wide standardized component, don't create new component file by file by yourself

bun run gc <layer> <ComponentName>
# Examples:
bun run gc shared Button
bun run gc feature AuthForm
bun run gc entity UserCard
bun run gc page HomePage
bun run gc widget Sidebar

---

Best Practices

Code Style

1. Small Functions — max 20-30 lines; extract helpers
2. Single Responsibility — one function = one purpose
3. Descriptive Names — getUserById not getData
4. Early Returns — reduce nesting with guard clauses
5. No Magic Values — use constants: const MAX_ITEMS = 10

TypeScript

// ✅ Use interfaces for props
interface IButtonProps {
	variant: "primary" | "secondary"
	disabled?: boolean
	onClick: () => void
}

// ✅ Prefer explicit types over `any`
// ✅ Use `type` for unions/intersections, `interface` for objects

React Patterns

// ✅ Functional components with explicit return type
export const Button: FC<IButtonProps> = ({ variant, onClick }): JSX.Element => { ... }

// ✅ Destructure props
// ✅ Use data-testid for testing
// ✅ Colocate styles with components (CSS Modules)

FSD Rules

1. Import Direction — only downward: features → entities → shared
2. Public API — export only through index.ts
3. No Cross-Slice Imports — features cannot import from other features
4. Shared is Agnostic — no business logic in shared layer

File Naming

Type	Convention	Example
Component	PascalCase	UserCard.tsx
Module	PascalCase.module	UserCard.module.scss
Types	PascalCase.d	UserCard.d.ts
Hook	camelCase (use-)	useAuth.ts
Utility	camelCase	formatDate.ts
Constant	UPPER_SNAKE_CASE	API_ENDPOINTS.ts

Performance

1. Use React.memo for expensive renders
2. Use useMemo / useCallback for derived data and callbacks
3. Lazy load pages/heavy components with next/dynamic
4. Prefer server components where possible (Next.js App Router)

Testing

• Place tests next to components: ComponentName.test.tsx
• Use data-testid attributes for queries
• Test behavior, not implementation

---

Icons Workflow

1. Place raw SVG in src/shared/assets/raw-icons/
2. Run bun run gicons
3. Import from @shared/ui/Icons/IconName

---

Notes

• Keep pages/ folder in root — removing causes Next.js build errors
• Bun only — use bun commands, not npm/yarn
• SCSS Modules — all styles are scoped via .module.scss
• Strict TypeScript — strict: true in tsconfig

---

Quick Reference

Task	Command / Location
Add dependency	bun add <package>
Add dev dependency	bun add -d <package>
Create component	bun run gc <layer> <Name>
Global styles	src/app/styles/global.scss
API client	Use Axios/Xior with React Query
State management	TanStack Query (server state)

Implementation sentiments

Write less complicated code, simple but readable code Less overhead - better Write all components with html semantics in mind