@dcyfr/ai-react

Production-ready React SPA starter template with modern tooling and enterprise patterns.

Perfect for building scalable single-page applications with full type safety, optimistic UI updates, and exceptional developer experience.

✅ Modern Stack - React 19, Vite 6, TypeScript 5.7+
✅ Type-Safe Routing - TanStack Router with file-based routes
✅ Smart State - Zustand for client state, React Query for server state
✅ UI Components - Pre-built components with Tailwind CSS
✅ Validation - Zod schemas for runtime type checking
✅ Testing - Vitest + React Testing Library (99% pass rate)
✅ Developer Experience - Fast HMR, auto-imports, strict TypeScript
✅ Production Ready - Optimized builds, code splitting, prefetching

---

First Steps After Installation

1. Start the dev server: npm run dev → http://localhost:3000
2. Explore the examples: Navigate to /examples to see counter and form patterns
3. Check the docs: Review docs/ directory for routing, state management, testing, and deployment guides

---

Tech Stack

Category	Technology	Version
Framework	React	19
Language	TypeScript	5.7+
Bundler	Vite	6
Routing	TanStack Router	1.95+
Server State	TanStack React Query	5.62+
Client State	Zustand	5
Styling	Tailwind CSS	3.4
Validation	Zod	3.24+
Testing	Vitest + React Testing Library	2.1 / 16.1

Quick Start

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm run test:run

# Type check
npm run typecheck

# Build for production
npm run build

# Preview production build
npm run preview

The dev server starts at http://localhost:3000.

Project Structure

dcyfr-ai-react/
├── index.html                  # HTML entry point
├── public/
│   └── favicon.svg             # App favicon
├── src/
│   ├── main.tsx                # Application entry (providers)
│   ├── config/
│   │   └── index.ts            # App configuration
│   ├── components/
│   │   ├── layout/
│   │   │   └── root-layout.tsx # App shell (navbar + footer)
│   │   └── ui/
│   │       ├── badge.tsx       # Badge component
│   │       ├── button.tsx      # Button with variants
│   │       ├── card.tsx        # Card container
│   │       ├── input.tsx       # Input with error state
│   │       └── spinner.tsx     # Loading spinner
│   ├── hooks/
│   │   ├── use-debounce.ts     # Debounce hook
│   │   ├── use-local-storage.ts# Local storage hook
│   │   └── use-media-query.ts  # Media query hook
│   ├── lib/
│   │   └── utils.ts            # cn() utility
│   ├── routes/
│   │   ├── router.tsx          # Route definitions
│   │   ├── home.tsx            # Home page
│   │   ├── about.tsx           # About page
│   │   ├── examples.tsx        # Examples (counter + form)
│   │   └── not-found.tsx       # 404 page
│   ├── services/
│   │   └── api-client.ts       # Typed API client
│   ├── stores/
│   │   ├── counter-store.ts    # Counter (example)
│   │   └── theme-store.ts      # Theme (dark/light/system)
│   └── styles/
│       └── globals.css         # Tailwind + CSS variables
└── tests/
    ├── setup.ts                # Test setup (jest-dom)
    ├── components/
    │   ├── badge.test.tsx
    │   ├── button.test.tsx
    │   ├── card.test.tsx
    │   └── input.test.tsx
    ├── hooks/
    │   └── use-debounce.test.ts
    ├── services/
    │   └── api-client.test.ts
    └── stores/
        ├── counter-store.test.ts
        └── theme-store.test.ts

Key Patterns

Type-Safe Routing (TanStack Router)

import { createRoute } from '@tanstack/react-router';

const myRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/my-page',
  component: MyPage,
});

State Management (Zustand)

import { create } from 'zustand';

interface MyState {
  value: string;
  setValue: (v: string) => void;
}

export const useMyStore = create<MyState>((set) => ({
  value: '',
  setValue: (v) => set({ value: v }),
}));

Typed API Client

import { apiClient } from '@/services/api-client';
import { z } from 'zod';

const UserSchema = z.object({ id: z.number(), name: z.string() });

const user = await apiClient.get('/users/1', UserSchema);
// user is typed as { id: number; name: string }

UI Components

All components support variant props and className merging via cn():

import { Button, Card, Badge } from '@/components/ui';

<Button variant="primary" size="lg">Click Me</Button>
<Card title="My Card">Content here</Card>
<Badge variant="secondary">Status</Badge>

Environment Variables

Test Coverage

Category	Tests	Status
Components	19	✅ Passing
Hooks	4	✅ Passing
Services	3	✅ Passing
Stores	8	✅ Passing
Total	34	✅ 99% Pass Rate

---

Documentation

Comprehensive guides in the docs/ directory:

• Routing Guide (604 lines) - TanStack Router patterns, type-safe search params, route loaders, code splitting, navigation guards
• State Management (757 lines) - Zustand + React Query patterns, optimistic updates, pagination, cache management
• Testing Guide (771 lines) - Vitest + RTL best practices, mocking, async testing, testing hooks/stores/queries
• Deployment Guide (801 lines) - Vercel, Netlify, Docker, AWS S3 + CloudFront, GitHub Pages, environment variables

Total: 2,933 lines of production-ready documentation.

---

Examples

The examples/ directory contains executable TypeScript examples:

1. Custom Hooks (examples/custom-hooks.tsx)

Reusable hooks for common patterns:

import { useForm, useDebounce, useLocalStorage } from './examples/custom-hooks';

// Form with validation
const form = useForm({
  initialValues: { email: '', password: '' },
  validationRules: { /* Zod-like rules */ },
  onSubmit: async (values) => { /* API call */ },
});

// Debounced search
const [searchTerm, setSearchTerm] = useState('');
const debouncedSearchTerm = useDebounce(searchTerm, 500);

// Persisted theme
const [theme, setTheme] = useLocalStorage<'light' | 'dark'>('theme', 'light');

2. Form Handling (examples/form-handling.tsx)

Complete form examples with Zod validation:

import { RegistrationForm, MultiStepForm } from './examples/form-handling';

// Complex registration form with async validation
<RegistrationForm />

// Multi-step form with progress tracking
<MultiStepForm />

3. Data Fetching (examples/data-fetching-patterns.tsx)

React Query patterns with error boundaries:

import { UserProfile, InfinitePostList, PostWithComments } from './examples/data-fetching-patterns';

// Basic query with loading/error states
<UserProfile userId={1} />

// Infinite scroll pagination
<InfinitePostList />

// Dependent queries (post → author → comments)
<PostWithComments postId={1} />

Total: 1,640 lines of production-quality examples.

---

Deployment

Quick Start (Vercel - Recommended)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

# Production
vercel --prod

Set environment variables in Vercel Dashboard:

VITE_API_URL=https://api.example.com

Docker Deployment

# Build image
docker build -t my-react-app .

# Run container
docker run -d -p 8080:80 my-react-app

See DEPLOYMENT.md for Netlify, GitHub Pages, AWS S3, and Kubernetes deployment guides.

---

Production Environment Variables

# Production API endpoint
VITE_API_URL=https://api.production.com

# App environment
VITE_APP_ENV=production

# Disable dev tools in production
VITE_ENABLE_DEVTOOLS=false

Important: All Vite env vars must start with VITE_ to be exposed to the client.

---

Performance Optimizations

• ✅ Code splitting - Lazy route loading with lazyRouteComponent
• ✅ Tree shaking - Vite removes unused code automatically
• ✅ Asset optimization - Images, CSS, and JS are minified and compressed
• ✅ Prefetching - Route data prefetched on link hover
• ✅ Caching - React Query manages server state with smart cache invalidation

---

Scripts Reference

Command	Description
npm run dev	Start dev server with HMR
npm run build	Build for production (optimized)
npm run preview	Preview production build locally
npm run typecheck	Run TypeScript type checking
npm run lint	Run ESLint
npm run test:run	Run all tests once
npm run test:watch	Run tests in watch mode
npm run test:coverage	Generate coverage report

---

Troubleshooting

Vite dev server won't start

Problem: Port 3000 already in use.

Solution:

# Use different port
npm run dev -- --port 3001

Environment variables not working

Problem: import.meta.env.API_URL is undefined.

Solution: Ensure the variable starts with VITE_:

❌ API_URL=https://api.example.com
✅ VITE_API_URL=https://api.example.com

404 errors on direct URL access

Problem: Routes return 404 when accessed directly after deployment.

Solution: Configure your hosting provider to serve index.html for all routes (see DEPLOYMENT.md).

---

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create your feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -m 'feat: add my feature'
4. Push to the branch: git push origin feature/my-feature
5. Open a Pull Request

Code Style:

• Follow existing TypeScript conventions
• Add tests for new features
• Update documentation for API changes
• Run npm run lint and npm run typecheck before committing

---

Roadmap

• Storybook integration for component documentation
• PWA support (service workers, offline mode)
• Internationalization (i18n) with react-i18next
• E2E testing with Playwright
• GitHub Actions CI/CD workflows
• Bundle size analysis and optimization
• Accessibility audit with jest-axe
• Performance monitoring with Web Vitals

---

Resources

• React Documentation
• Vite Documentation
• TanStack Router
• TanStack Query
• Zustand Documentation

---

License: MIT
Maintained by: DCYFR Labs
Last Updated: February 7, 2026

Variable	Description	Default
VITE_API_URL	Backend API base URL	/api

Copy .env.example to .env and configure as needed.

Testing

# Run all tests
npm run test:run

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage

Tests use Vitest with React Testing Library and jsdom environment.

Building

# Production build
npm run build

# Preview the build
npm run preview

Output is generated in dist/.

License

MIT - See LICENSE for details.