FastReact Framework

A powerful CLI framework for rapid full-stack application development with React and FastAPI

FastReact enables developers to create complete full-stack applications with a single command, providing seamless integration between React frontend and FastAPI backend through pre-built templates, automatic API client generation, and unified development environment.

🚀 Quick Start

Installation

npm install -g fastreact

Create Your First Project

# Create a new project with the base template
fastreact setup my-app

# Or with specific options
fastreact setup my-calculator --template calculator --auth --typescript

# Navigate to your project
cd my-app

# Start development servers
fastreact dev

Your full-stack application is now running at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000/docs

✨ Features

🎯 Zero Configuration

• Complete full-stack setup with a single command
• Pre-configured development environment
• Automatic hot reloading for both frontend and backend

📦 Template-Driven Development

• Base: Minimal React + FastAPI setup
• Calculator: Interactive calculator with history
• Todo: Task management with CRUD operations
• Blog: Article management with commenting system

🔄 Seamless Integration

• Automatic API proxy configuration
• Generated API client with React hooks
• Type-safe communication between frontend and backend

🛠️ Modern Technology Stack

• Frontend: React 18, Vite, TypeScript (optional)
• Backend: FastAPI, Uvicorn, Pydantic
• Development: Hot reloading, ESLint, Prettier

📋 Prerequisites

• Node.js 16.0.0 or higher
• Python 3.8 or higher
• npm or yarn package manager

🔧 CLI Commands

Project Creation

# Basic project setup
fastreact setup <project-name>

# With template selection
fastreact setup my-blog --template blog

# With additional features
fastreact setup my-app --auth --websocket --typescript

# Skip dependency installation
fastreact setup my-app --no-install

# Skip confirmation prompts
fastreact setup my-app --template base -y

Available Options:

• --template, -t: Choose template (base, calculator, todo, blog)
• --typescript: Enable TypeScript support
• --auth: Include JWT authentication
• --websocket: Add WebSocket integration
• --database: Database type (sqlite, postgresql, mysql)
• --no-install: Skip dependency installation
• -y, --yes: Skip confirmation prompts

Development

# Start development servers
fastreact dev

# Custom ports
fastreact dev --frontend-port 3001 --backend-port 8001

# Disable API proxy
fastreact dev --no-proxy

# Custom host
fastreact dev --host 0.0.0.0

Code Generation

# Generate API client from FastAPI schema
fastreact generate-api

# Generate only React hooks
fastreact generate-api --hooks-only

# Custom output directory
fastreact generate-api --output src/api

Project Management

# Build for production
fastreact build

# Add features to existing project
fastreact add auth
fastreact add websocket
fastreact add testing

# Project information
fastreact info

# Diagnose issues
fastreact doctor

# Interactive configuration
fastreact config

📁 Project Structure

my-project/
├── package.json                 # Frontend dependencies
├── vite.config.js              # Vite configuration
├── fastreact.config.js         # FastReact framework config
├── .env                        # Environment variables
├── src/                        # React frontend
│   ├── main.jsx               # App entry point
│   ├── App.jsx                # Main component
│   ├── components/            # Reusable components
│   ├── pages/                 # Page components
│   ├── hooks/                 # Custom React hooks
│   │   └── useAPI.js         # API hooks
│   ├── utils/                 # Utilities
│   │   ├── apiClient.js      # Generated API client
│   │   └── constants.js      # App constants
│   └── styles/                # CSS files
├── backend/                    # FastAPI backend
│   ├── main.py               # FastAPI app
│   ├── requirements.txt      # Python dependencies
│   ├── models/               # Data models
│   ├── routes/               # API routes
│   │   ├── health.py        # Health check endpoints
│   │   └── api.py           # Main API routes
│   ├── services/             # Business logic
│   └── utils/                # Backend utilities
├── scripts/                   # Development scripts
│   ├── dev.js               # Development server
│   ├── build.js             # Build script
│   └── deploy.js            # Deployment script
└── tests/                     # Test files
    ├── frontend/            # Frontend tests
    ├── backend/             # Backend tests
    └── e2e/                 # End-to-end tests

🎨 Templates

Base Template

Minimal setup with essential features:

• React app with routing
• FastAPI with health check
• API client and hooks
• Development configuration

Calculator Template

Interactive calculator application:

• Mathematical operations
• Calculation history
• Theme toggling
• Keyboard support

Todo Template

Task management application:

• CRUD operations
• Task filtering and search
• Bulk operations
• Priority management

Blog Template

Content management system:

• Article creation and editing
• Comment system
• Category management
• Admin panel

🔧 Configuration

FastReact Configuration (fastreact.config.js)

module.exports = {
  // Development server
  development: {
    frontendPort: 3000,
    backendPort: 8000,
    apiPrefix: '/api',
    autoProxy: true,
    hotReload: true,
    openBrowser: true
  },
  
  // API client
  api: {
    timeout: 5000,
    retries: 3,
    cacheEnabled: true,
    baseURL: process.env.NODE_ENV === 'production' 
      ? 'https://api.myapp.com' 
      : 'http://localhost:8000'
  },
  
  // Build settings
  build: {
    outputDir: 'dist',
    sourceMaps: true,
    minify: true
  },
  
  // Template settings
  template: {
    name: 'base',
    features: ['auth', 'websocket'],
    database: {
      type: 'sqlite',
      url: 'sqlite:///./app.db'
    }
  }
};

Environment Variables (.env)

# Development
VITE_API_URL=http://localhost:8000
VITE_FRONTEND_PORT=3000
VITE_BACKEND_PORT=8000

# Production
VITE_API_URL=https://your-api-domain.com

# Backend
DATABASE_URL=sqlite:///./app.db
SECRET_KEY=your-secret-key-here

🪝 API Integration

Auto-Generated API Client

FastReact automatically generates a type-safe API client based on your FastAPI schema:

import { api } from './utils/apiClient';

// Generated methods
const response = await api.get('/api/items');
const item = await api.post('/api/items', { name: 'New Item' });

React Hooks

Use the generated React hooks for seamless API integration:

import { useAPI, useMutation } from './hooks/useAPI';

function ItemList() {
  const { data: items, loading, error, refetch } = useAPI('/api/items');
  const { mutate: createItem } = useMutation('/api/items');
  
  const handleCreate = async (itemData) => {
    await createItem(itemData);
    refetch(); // Refresh the list
  };
  
  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return (
    <div>
      {items.map(item => (
        <div key={item.id}>{item.name}</div>
      ))}
    </div>
  );
}

🧪 Testing

FastReact includes testing setup for comprehensive coverage:

Frontend Testing

# Unit tests with Jest
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Backend Testing

# Python tests with pytest
cd backend
pytest

# With coverage
pytest --cov=.

End-to-End Testing

# Playwright E2E tests
npm run test:e2e

🚀 Deployment

Frontend Deployment

# Build for production
fastreact build

# Deploy to Vercel
vercel deploy

# Deploy to Netlify
netlify deploy --prod --dir=dist

Backend Deployment

# Docker deployment
docker build -t my-app-backend ./backend
docker run -p 8000:8000 my-app-backend

# Cloud deployment (example with Railway)
railway deploy

🛠️ Development Workflow

1. Create Project

   fastreact setup my-app --template todo
   cd my-app

2. Start Development

   fastreact dev

3. Develop Features

   • Add React components in src/components/
   • Create API endpoints in backend/routes/
   • Update data models in backend/models/

4. Generate API Client

   fastreact generate-api

5. Test Your App

   npm test
   cd backend && pytest

6. Build and Deploy

   fastreact build
   # Deploy using your preferred platform

🔍 Debugging and Diagnostics

Project Health Check

fastreact doctor

This command checks:

• Node.js and Python versions
• Dependency installation status
• Port availability
• Project structure integrity
• Configuration validity

Development Tips

1. API Debugging: Visit http://localhost:8000/docs for interactive API documentation
2. Hot Reloading: Both frontend and backend support hot reloading
3. Error Handling: Check browser console and terminal for detailed error messages
4. Port Conflicts: Use fastreact doctor to detect and resolve port issues

🆘 Troubleshooting

Common Issues

Port Already in Use

fastreact dev --frontend-port 3001 --backend-port 8001

Dependencies Not Installing

npm install
pip install -r backend/requirements.txt

API Client Out of Sync

fastreact generate-api

Python Import Errors Make sure you're in the correct directory and have activated your virtual environment.

Getting Help

• Check the documentation: fastreact --help
• Run diagnostics: fastreact doctor
• View project info: fastreact info

🤝 Contributing

We welcome contributions! Please read our Contributing Guide for details.

Development Setup

1. Clone the repository
2. Install dependencies: npm install
3. Run tests: npm test
4. Create your feature branch
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• React - Frontend framework
• FastAPI - Backend framework
• Vite - Build tool
• Commander.js - CLI framework

📊 Project Status

FastReact is actively maintained and under continuous development. Current version implements:

✅ Completed Features:

• Basic project scaffolding
• Base template with React + FastAPI
• Development server with hot reloading
• API client generation foundations
• Project diagnostics and health checks

🚧 In Development:

• Calculator, Todo, and Blog templates
• Advanced API client generation
• Authentication system integration
• WebSocket support
• TypeScript template variants

📋 Planned Features:

• Database migration system
• Docker containerization
• Cloud deployment integrations
• Plugin system for extensions
• GraphQL support

Happy coding with FastReact! 🚀

For more information, visit our GitHub repository.