@toolkit/template

A fully configured React + Vite template with TDD, clean code, and mobile-first design.

Getting Started

Setup

npm install
npm run dev

Visit http://localhost:5173

Scripts

npm run dev              # Start dev server
npm run build            # Build for production
npm run preview          # Preview production build
npm run test             # Run tests once
npm run test:watch       # Run tests in watch mode
npm run lint             # Run ESLint
npm run type-check       # Check TypeScript

What's Pre-Configured

✅ Vite - Lightning-fast dev server with HMR ✅ React 19.2 - Latest React with hooks ✅ TypeScript - Full type safety with strict mode ✅ Tailwind CSS 4.2 - Utility-first CSS with @/ path alias ✅ Shadcn/ui - Accessible component library (5 base components) ✅ TanStack Query - Server state management with React Query ✅ Axios - HTTP client with interceptors ✅ Zustand - Global state management (auth, ui) ✅ React Hook Form - Performant form handling ✅ Zod - Schema validation ✅ ESLint - Code quality ✅ Jest - Testing framework ✅ i18n - Internationalization (pt, en)

Project Structure

src/
├── features/
│   └── shared/
│       ├── components/ui/       # Shadcn base components
│       ├── hooks/               # Reusable hooks (useSearch, useDebounce, etc)
│       ├── services/api/        # apiClient, endpoints, queryClient
│       └── store/               # Zustand stores (authStore, uiStore)
├── pages/                       # Generic pages
├── routes/index.tsx             # Route configuration
├── i18n/locales/                # Translations
├── styles/globals.css           # Global styles
├── App.tsx
└── main.tsx

Creating Features

Use the CLI to scaffold new features:

npx @toolkit/cli create-feature domain/subdomain/featureName

Example:

npx @toolkit/cli create-feature admin/financial/contracts

This creates a complete feature with:

• TypeScript types + Zod schemas
• React Query services
• Custom form hook with React Hook Form
• Components (form, card, list)
• Integration tests

Conventions

See root CLAUDE.md for detailed conventions:

• TDD: Write tests before code
• Logic-Presentation Separation: Logic in hooks, UI in components
• Clean Code: No comments, self-explanatory naming
• Mobile-First: Design for small screens first
• Reusability: Extract duplicated logic to hooks

API Integration

1. Define Endpoints

// src/features/shared/services/api/endpoints.ts
export const CONTRACT_ENDPOINTS = {
  LIST: '/contracts',
  GET: (id) => `/contracts/${id}`,
  CREATE: '/contracts',
  UPDATE: (id) => `/contracts/${id}`,
  DELETE: (id) => `/contracts/${id}`,
};

2. Create Service Hooks

// src/features/admin/financial/contracts/contract.services.ts
import { useQuery, useMutation } from '@tanstack/react-query';
import { apiClient } from '@/shared/services/api/apiClient';

export const useGetContracts = () =>
  useQuery({
    queryKey: ['contracts'],
    queryFn: () => apiClient.get(CONTRACT_ENDPOINTS.LIST),
  });

3. Use in Hooks

// src/features/admin/financial/contracts/hooks/useContractForm.tsx
export function useContractForm(onSuccess) {
  const { mutate: create } = useCreateContract();
  // Form logic...
}

4. Use in Components

// src/features/admin/financial/contracts/pages/ContractListPage.tsx
export function ContractListPage() {
  const form = useContractForm();
  return <ContractForm {...form} />;
}

Testing

Tests follow TDD: write tests before code.

Run Tests

npm run test              # Single run
npm run test:watch       # Watch mode
npm run test -- --coverage

Test Examples

Hook Test:

describe('useContractForm', () => {
  it('initializes with empty form', () => {
    const { result } = renderHook(() => useContractForm());
    expect(result.current.isValid).toBe(false);
  });
});

Component Test:

describe('ContractForm', () => {
  it('renders form fields', () => {
    render(<ContractForm {...mockProps} />);
    expect(screen.getByLabelText(/title/i)).toBeInTheDocument();
  });
});

Environment Variables

Create .env.local:

VITE_API_URL=http://localhost:3000/api
VITE_APP_NAME=My App

Deployment

Build

npm run build

Output: dist/

Deploy to Vercel

vercel deploy

Deploy to Netlify

Connect repository and Netlify will auto-deploy on push.

Troubleshooting

Port 5173 already in use

npm run dev -- --port 3000

ESLint errors

npx eslint src --fix

TypeScript errors

npm run type-check

Learn More

• React Documentation
• Vite Documentation
• Tailwind CSS
• TanStack Query
• Zod

License

MIT