front init
This commit is contained in:
Daniil
@@ -0,0 +1,217 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```ts
|
||||
@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
|
||||
|
||||
```tsx
|
||||
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
|
||||
|
||||
```bash
|
||||
bun run gc <layer> <ComponentName>
|
||||
# Examples:
|
||||
bun run gc shared Button
|
||||
bun run gc features AuthForm
|
||||
bun run gc entities UserCard
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
```ts
|
||||
// ✅ 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
|
||||
|
||||
```tsx
|
||||
// ✅ 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) |
|
||||
Reference in New Issue
Block a user