AGENTS.md - AI Agent Guidelines

This document provides instructions and guidelines for AI agents (like Claude) working on this React Boilerplate project.

Project Overview

Type: React TypeScript Boilerplate
Package Manager: Bun
Build Tool: Vite
Testing Framework: Vitest
Runtime: Bun (no Node.js dependency)

Build & Development Instructions

Prerequisites

Ensure you have the following installed:

Bun 1.3.4 or later
Git

Setting Up the Project

# Install dependencies
bun install

# Start development server (http://localhost:5173/)
bun start

# Build for production
bun run build

# Preview production build
bun run serve

# Run tests (watch mode)
bun run test

# Run tests with coverage report
bun run test:coverage

# Run ESLint
bun run lint

# Extract i18n messages
bun run i18n:extract

# Initialize MSW (Mock Service Worker)
bun run msw

Important Commands

Command	Purpose
`bun install`	Install dependencies using bun.lock
`bun install --frozen-lockfile`	Install with locked dependencies (CI/CD)
`bun start`	Run dev server with auto-reload
`bun run build`	Build TypeScript and bundle with Vite
`bun run test`	Run all tests in watch mode
`bun run test:coverage`	Run tests with coverage report
`bun run lint`	Check code style with ESLint

Coding Style Guide

TypeScript/JavaScript

Language: TypeScript (strict mode)
Style: Enforce with ESLint
Format: 2 spaces indentation
Imports: Use ES6 modules (
```
import
```
/
```
export
```
)
Arrow Functions: Preferred for callbacks and event handlers

Do's

// Use type annotations
const count: number = 0;

// Use arrow functions
const handleClick = () => { /* ... */ };

// Use const for immutability
const config = { /* ... */ };

// Use proper typing
interface User {
  id: string;
  name: string;
}

// Destructure props
const MyComponent = ({ name, age }: Props) => {
  return <div>{name}</div>;
};

Don'ts

// Avoid any type
const data: any = null; // ❌

// Avoid var
var count = 0; // ❌

// Avoid loose typing
const config = { /* ... */ }; // ❌ without type annotation

// Avoid function declarations in components
function MyComponent() { } // ❌

React Components

Functional Components: Always use functional components with hooks
Naming: PascalCase for components
Files: One component per file (unless tightly coupled)
Hooks: Use standard React hooks (useState, useEffect, useContext, etc.)

Component Structure

// File: src/components/MyComponent.tsx
import { FC } from 'react';

interface MyComponentProps {
  title: string;
  onClose?: () => void;
}

export const MyComponent: FC<MyComponentProps> = ({ title, onClose }) => {
  return (
    <div>
      <h1>{title}</h1>
      {onClose && <button onClick={onClose}>Close</button>}
    </div>
  );
};

File Organization

src/
├── components/          # React components
│   ├── NavMenu.tsx
│   ├── Counter.tsx
│   └── ...
├── api/                 # API services and requests
│   ├── TodoService.ts
│   └── ...
├── hooks/               # Custom React hooks
├── i18n.ts              # i18n configuration
├── setupTests.ts        # Test setup
├── setupStoragePolyfill.ts  # Storage polyfill
├── App.tsx              # Root component
├── index.tsx            # Entry point
└── styles/              # Global styles (CSS)

Testing

Framework: Vitest
Testing Library: React Testing Library
Coverage: Track with codecov
Pattern: Test file name =
```
ComponentName.test.tsx
```

Test Example

import { render, screen } from '@testing-library/react';
import { MyComponent } from './MyComponent';

describe('MyComponent', () => {
  it('should render title', () => {
    render(<MyComponent title="Test" />);
    expect(screen.getByText('Test')).toBeInTheDocument();
  });
});

Imports & Exports

Use named exports for components (not default exports)
Use absolute imports where possible
Group imports: React → External libraries → Local imports

import { FC } from 'react';
import { useTranslation } from 'react-i18next';

import { TodoService } from '../api/TodoService';
import { Button } from './Button';

Code Quality Standards

ESLint Configuration

The project enforces ESLint rules defined in

.eslintrc.json

. Run before committing:

bun run lint

TypeScript Checks

The build process includes TypeScript compilation:

# Runs as part of: bun run build
tsc --noEmit

Test Coverage

Maintain high test coverage. All public components and utilities should have tests.

bun run test:coverage

Development Guidelines

When Making Changes

Before modifying files: Read existing code to understand patterns and architecture
Follow existing patterns: Match the style of surrounding code
Avoid over-engineering: Keep solutions simple and focused
No unnecessary refactoring: Don't refactor code that isn't directly related to the task
Minimal comments: Only comment non-obvious logic

Editing Existing Code

Prefer editing existing files over creating new ones
Don't add docstrings, comments, or type annotations to unchanged code
Only add comments where logic isn't self-evident
Delete unused code completely (no "// removed" comments)

Creating New Files

Only create new files when absolutely necessary:

New components require their own files
Utility functions can be grouped in utilities directory
Don't create documentation files unless explicitly requested

Git Commits

Write clear, concise commit messages (1-2 sentences)
Focus on "why" rather than "what"

Example:

Add dark mode toggle to application settings

Dependencies

Don't add new dependencies without justification
Prefer built-in solutions and existing libraries
Check package.json for duplicates before adding

Project-Specific Configuration

Vite Configuration (vite.config.ts)

Development server: Vite with HMR
Build target: ESNext
Test environment: jsdom with storage polyfill
No warnings suppressed:
```
NODE_NO_WARNINGS=1
```
(jsdom/Bun compatibility)

i18n Configuration

Language files:
```
src/i18n/locales/
```
Default language: English
Auto language detection enabled
Use
```
useTranslation()
```
hook in components

MSW (Mock Service Worker)

Mock handlers:
```
src/mocks/handlers.ts
```
Browser setup:
```
public/mockServiceWorker.js
```
(auto-generated)
Server setup in tests:
```
src/setupTests.ts
```

Common Tasks

Adding a New Component

# 1. Create the component file
# File: src/components/MyNewComponent.tsx

import { FC } from 'react';

interface MyNewComponentProps {
  // Define props
}

export const MyNewComponent: FC<MyNewComponentProps> = (props) => {
  return <div>Component content</div>;
};

# 2. Create test file
# File: src/components/MyNewComponent.test.tsx

# 3. Test it
bun run test

# 4. Run linter
bun run lint

Adding a New API Service

// File: src/api/MyService.ts
export class MyService {
  static async fetch() {
    const response = await fetch('/api/endpoint');
    return response.json();
  }
}

Adding Tests

Use Vitest with React Testing Library
Test user interactions, not implementation details
Mock external dependencies
Aim for high coverage but prioritize meaningful tests

Troubleshooting

Build Issues

Clear cache and reinstall:

rm -rf node_modules bun.lock
bun install

Check TypeScript errors:
```
bun run build
```

Test Issues

Run tests with verbose output:

bun run test -- --reporter=verbose

Debug a specific test:

bun run test MyComponent.test.tsx

Linting Issues

bun run lint

Resources

Questions?

For questions about the project structure or development workflow, refer to the main README.md or examine existing code examples in the repository.

AGENTS.md - AI Agent Guidelines

This document provides instructions and guidelines for AI agents (like Claude) working on this React Boilerplate project.

Project Overview

Type: React TypeScript Boilerplate
Package Manager: Bun
Build Tool: Vite
Testing Framework: Vitest
Runtime: Bun (no Node.js dependency)

Build & Development Instructions

Prerequisites

Ensure you have the following installed:

Bun 1.3.4 or later
Git

Setting Up the Project

# Install dependencies
bun install

# Start development server (http://localhost:5173/)
bun start

# Build for production
bun run build

# Preview production build
bun run serve

# Run tests (watch mode)
bun run test

# Run tests with coverage report
bun run test:coverage

# Run ESLint
bun run lint

# Extract i18n messages
bun run i18n:extract

# Initialize MSW (Mock Service Worker)
bun run msw

Important Commands

Command	Purpose
`bun install`	Install dependencies using bun.lock
`bun install --frozen-lockfile`	Install with locked dependencies (CI/CD)
`bun start`	Run dev server with auto-reload
`bun run build`	Build TypeScript and bundle with Vite
`bun run test`	Run all tests in watch mode
`bun run test:coverage`	Run tests with coverage report
`bun run lint`	Check code style with ESLint

Coding Style Guide

TypeScript/JavaScript

Language: TypeScript (strict mode)
Style: Enforce with ESLint
Format: 2 spaces indentation
Imports: Use ES6 modules (
```
import
```
/
```
export
```
)
Arrow Functions: Preferred for callbacks and event handlers

Do's

// Use type annotations
const count: number = 0;

// Use arrow functions
const handleClick = () => { /* ... */ };

// Use const for immutability
const config = { /* ... */ };

// Use proper typing
interface User {
  id: string;
  name: string;
}

// Destructure props
const MyComponent = ({ name, age }: Props) => {
  return <div>{name}</div>;
};

Don'ts

// Avoid any type
const data: any = null; // ❌

// Avoid var
var count = 0; // ❌

// Avoid loose typing
const config = { /* ... */ }; // ❌ without type annotation

// Avoid function declarations in components
function MyComponent() { } // ❌

React Components

Functional Components: Always use functional components with hooks
Naming: PascalCase for components
Files: One component per file (unless tightly coupled)
Hooks: Use standard React hooks (useState, useEffect, useContext, etc.)

Component Structure

// File: src/components/MyComponent.tsx
import { FC } from 'react';

interface MyComponentProps {
  title: string;
  onClose?: () => void;
}

export const MyComponent: FC<MyComponentProps> = ({ title, onClose }) => {
  return (
    <div>
      <h1>{title}</h1>
      {onClose && <button onClick={onClose}>Close</button>}
    </div>
  );
};

File Organization

src/
├── components/          # React components
│   ├── NavMenu.tsx
│   ├── Counter.tsx
│   └── ...
├── api/                 # API services and requests
│   ├── TodoService.ts
│   └── ...
├── hooks/               # Custom React hooks
├── i18n.ts              # i18n configuration
├── setupTests.ts        # Test setup
├── setupStoragePolyfill.ts  # Storage polyfill
├── App.tsx              # Root component
├── index.tsx            # Entry point
└── styles/              # Global styles (CSS)

Testing

Framework: Vitest
Testing Library: React Testing Library
Coverage: Track with codecov
Pattern: Test file name =
```
ComponentName.test.tsx
```

Test Example

import { render, screen } from '@testing-library/react';
import { MyComponent } from './MyComponent';

describe('MyComponent', () => {
  it('should render title', () => {
    render(<MyComponent title="Test" />);
    expect(screen.getByText('Test')).toBeInTheDocument();
  });
});

Imports & Exports

Use named exports for components (not default exports)
Use absolute imports where possible
Group imports: React → External libraries → Local imports

import { FC } from 'react';
import { useTranslation } from 'react-i18next';

import { TodoService } from '../api/TodoService';
import { Button } from './Button';

Code Quality Standards

ESLint Configuration

The project enforces ESLint rules defined in

.eslintrc.json

. Run before committing:

bun run lint

TypeScript Checks

The build process includes TypeScript compilation:

# Runs as part of: bun run build
tsc --noEmit

Test Coverage

Maintain high test coverage. All public components and utilities should have tests.

bun run test:coverage

Development Guidelines

When Making Changes

Before modifying files: Read existing code to understand patterns and architecture
Follow existing patterns: Match the style of surrounding code
Avoid over-engineering: Keep solutions simple and focused
No unnecessary refactoring: Don't refactor code that isn't directly related to the task
Minimal comments: Only comment non-obvious logic

Editing Existing Code

Prefer editing existing files over creating new ones
Don't add docstrings, comments, or type annotations to unchanged code
Only add comments where logic isn't self-evident
Delete unused code completely (no "// removed" comments)

Creating New Files

Only create new files when absolutely necessary:

New components require their own files
Utility functions can be grouped in utilities directory
Don't create documentation files unless explicitly requested

Git Commits

Write clear, concise commit messages (1-2 sentences)
Focus on "why" rather than "what"

Example:

Add dark mode toggle to application settings

Dependencies

Don't add new dependencies without justification
Prefer built-in solutions and existing libraries
Check package.json for duplicates before adding

Project-Specific Configuration

Vite Configuration (vite.config.ts)

Development server: Vite with HMR
Build target: ESNext
Test environment: jsdom with storage polyfill
No warnings suppressed:
```
NODE_NO_WARNINGS=1
```
(jsdom/Bun compatibility)

i18n Configuration

Language files:
```
src/i18n/locales/
```
Default language: English
Auto language detection enabled
Use
```
useTranslation()
```
hook in components

MSW (Mock Service Worker)

Mock handlers:
```
src/mocks/handlers.ts
```
Browser setup:
```
public/mockServiceWorker.js
```
(auto-generated)
Server setup in tests:
```
src/setupTests.ts
```

Common Tasks

Adding a New Component

# 1. Create the component file
# File: src/components/MyNewComponent.tsx

import { FC } from 'react';

interface MyNewComponentProps {
  // Define props
}

export const MyNewComponent: FC<MyNewComponentProps> = (props) => {
  return <div>Component content</div>;
};

# 2. Create test file
# File: src/components/MyNewComponent.test.tsx

# 3. Test it
bun run test

# 4. Run linter
bun run lint

Adding a New API Service

// File: src/api/MyService.ts
export class MyService {
  static async fetch() {
    const response = await fetch('/api/endpoint');
    return response.json();
  }
}

Adding Tests

Use Vitest with React Testing Library
Test user interactions, not implementation details
Mock external dependencies
Aim for high coverage but prioritize meaningful tests

Troubleshooting

Build Issues

Clear cache and reinstall:

rm -rf node_modules bun.lock
bun install

Check TypeScript errors:
```
bun run build
```

Test Issues

Run tests with verbose output:

bun run test -- --reporter=verbose

Debug a specific test:

bun run test MyComponent.test.tsx

Linting Issues

bun run lint

Resources

Questions?

For questions about the project structure or development workflow, refer to the main README.md or examine existing code examples in the repository.

AGENTS.md - AI Agent Guidelines

Related Skills

Markdown Converter

Nano Banana Pro

1password