React Velocity

A modern CLI tool to generate React projects using the Velocity Layer Architecture (VLA) - a production-ready structure that organizes code into logical layers for maximum developer velocity and maintainability.

🏗️ Velocity Layer Architecture (VLA)

VLA is our signature architecture that combines:

• ⚡ Performance-First: Built with Vite for instant dev server and builds
• 🎨 Design System: TailwindCSS with organized theme and animation layers
• 🏢 Enterprise-Ready: Professional folder structure for scalable applications
• 🔒 Security Built-In: Route guards, authentication, and permission layers
• 🧪 Test-Ready: Pre-configured testing utilities and setup

Features

• ⚡ Lightning Fast: Built with Vite for instant dev server and builds
• 🎨 TailwindCSS: Latest Vite plugin integration with organized design tokens
• 📁 Multiple Project Types: Choose from Web, Admin, or Combined project structures
• 🏗️ VLA Structure: Professional layered architecture for enterprise applications
• ⚛️ React Context: Pre-configured Context API with authentication hooks
• 🛠️ Development Ready: Complete API layer, guards, and utility functions
• 📦 Modern Tooling: Latest versions with ES modules and best practices

Quick Start

npx react-velocity

The CLI will prompt you for:

• Project name: Your project's name
• Project type: Choose from:
  • Web: Standard web application structure
  • Admin: Admin dashboard with authentication
  • Combined: Both web and admin in one project

📂 Velocity Layer Architecture Structure

Web Application (VLA)

your-project/
├── src/
│   ├── apis/           # API Layer
│   │   ├── axiosInstance.js  # Configured HTTP client
│   │   ├── constants.js      # API endpoints & config
│   │   └── apiService.js     # Service methods
│   ├── assets/         # Static assets
│   ├── config/         # Configuration Layer
│   │   └── app.js      # App-wide configuration
│   ├── constants/      # Constants Layer
│   │   └── index.js    # Routes, keys, permissions
│   ├── context/        # State Layer
│   │   └── AppContext.jsx
│   ├── guards/         # Security Layer
│   │   └── AuthGuard.jsx     # Route protection
│   ├── hooks/          # Logic Layer
│   │   ├── useAuth.js
│   │   └── useFetch.js
│   ├── layouts/        # Layout Layer
│   │   ├── MainLayout.jsx
│   │   └── AuthLayout.jsx
│   ├── lib/            # Integration Layer
│   │   └── setup.js    # Third-party configs
│   ├── pages/          # Presentation Layer
│   │   ├── auth/       # Authentication pages
│   │   └── modals/     # Modal components
│   ├── routing/        # Navigation Layer
│   │   └── routes.jsx
│   ├── ui/             # Design System Layer
│   │   ├── animations/ # Animation utilities
│   │   ├── colors/     # Color system
│   │   ├── icons/      # Icon components
│   │   └── theme/      # Theme configuration
│   ├── __tests__/      # Testing Layer
│   │   └── setup.js    # Test utilities
│   ├── App.jsx
│   └── main.jsx
├── public/
├── index.html
├── vite.config.js      # Vite + TailwindCSS plugin
└── package.json

Admin Dashboard (VLA)

Same professional structure optimized for admin interfaces with dashboard-specific components.

Combined Project (VLA)

your-project/
├── src/
│   ├── apis/           # Shared API layer
│   ├── config/         # Shared configuration
│   ├── constants/      # Shared constants
│   ├── guards/         # Shared route protection
│   ├── layouts/
│   │   ├── web/        # Web-specific layouts
│   │   └── admin/      # Admin-specific layouts
│   ├── pages/
│   │   ├── web/        # Web pages & modals
│   │   └── admin/      # Admin pages & modals
│   ├── ui/
│   │   ├── web/        # Web components
│   │   ├── admin/      # Admin components
│   │   ├── colors/     # Shared design tokens
│   │   ├── theme/      # Shared theme system
│   │   └── animations/ # Shared animations
│   └── ...

What's Included in VLA

🔧 Configuration Layer

• App Config: Centralized application settings
• Vite: Optimized React setup with TailwindCSS plugin
• Environment: Structured config management

🌐 API Layer

• Axios Instance: Pre-configured HTTP client with interceptors
• API Service: Complete CRUD operations and auth methods
• Constants: Centralized endpoint and configuration management

🔒 Security Layer

• Route Guards: Authentication and permission-based protection
• Auth Hooks: Secure state management for user sessions
• Protected Routes: Automatic redirection and access control

🎨 Design System Layer

• Theme System: Light/dark mode with consistent design tokens
• Animation Utils: Pre-built animation configurations
• Color System: Organized color palette and utilities
• Icon System: Scalable icon component structure

🧪 Testing Layer

• Test Setup: Pre-configured testing utilities
• Mock Functions: Ready-to-use test helpers
• Component Testing: Wrapper components for testing

🛠️ Development Layer

• Custom Hooks: Authentication, data fetching, and utilities
• Library Setup: Third-party integration configurations
• Constants: Routes, permissions, and app-wide constants

Getting Started

After creating your project:

cd your-project-name
npm install
npm run dev

Visit http://localhost:5173 to see your application.

Available Scripts

npm run dev          # Start development server
npm run build        # Build for production
npm run preview      # Preview production build

Requirements

• Node.js 14.0.0 or higher
• npm or yarn

🏆 VLA Benefits

Why Choose Velocity Layer Architecture?

• 🚀 Faster Development: Logical layer separation speeds up feature development
• 📈 Scalable: Professional structure that grows with your application
• 🧹 Maintainable: Clear separation of concerns makes debugging easier
• 👥 Team-Friendly: Consistent structure that teams can quickly understand
• 🏢 Enterprise-Ready: Production-grade organization suitable for large applications
• 🔧 Configurable: Modular design allows easy customization and extension

Project Types Comparison

| Feature | Web (VLA) | Admin (VLA) | Combined (VLA) | |---------|-----------|-------------|----------------| | VLA Structure | ✅ | ✅ | ✅ | | Security Layer | ✅ | ✅ | ✅ | | Design System | ✅ | ✅ | ✅ | | API Layer | ✅ | ✅ | ✅ | | Testing Layer | ✅ | ✅ | ✅ | | Admin Dashboard | ❌ | ✅ | ✅ | | Public Pages | ✅ | ❌ | ✅ | | Role-based Guards | ✅ | ✅ | ✅ |

License

MIT