Velox Starter Kit 🚀

A production-ready React starter template powered by modern web technologies and best practices.

---

Table of Contents

• Overview
• Features
• Tech Stack
• Project Structure
• Getting Started
  • Prerequisites
  • Installation
  • Development
  • Build
• Workflow & Collaboration
• Code Quality
• Contributing
• License

---

Overview

Velox Starter Kit is an opinionated, production-ready React boilerplate designed to accelerate your development workflow. It combines industry-standard tools with a well-structured architecture, allowing you to focus on building features instead of configuring tooling.

This starter kit is perfect for:

• ✅ Building modern web applications with type safety
• ✅ Teams following strict collaboration and commit conventions
• ✅ Projects requiring server-state management and type-safe routing
• ✅ Developers who want a pre-configured setup without compromises

---

Features

🔥 Core Technologies

• React 18 - Modern UI library with Hooks and Concurrent Features
• TypeScript - Type-safe JavaScript for scalable codebases
• Vite - Lightning-fast build tool with instant HMR
• Tailwind CSS v4 - Utility-first CSS framework with zero configuration

🎨 UI & Components

• Shadcn UI - Beautiful, accessible, and customizable component library
• Dark Mode Support - Built-in theme toggle with system preference detection
• Responsive Design - Mobile-first approach with Tailwind utilities

🛣️ Routing & Data Fetching

• TanStack Router - Type-safe, file-based routing with loaders
• TanStack Query - Powerful server-state management with automatic caching
• Axios - Promise-based HTTP client for API integration

📋 Forms & Validation

• React Hook Form - Performant form handling
• Zod - TypeScript-first schema validation

🧰 Developer Experience

• ESLint - Code linting with React and TypeScript rules
• Prettier - Opinionated code formatter
• Path Aliases - Clean imports with @/ prefix
• Conventional Commits - Standardized commit messages for better collaboration

---

Tech Stack

Technology	Purpose
	Build tool & dev server
	UI library
	Type safety
	Styling
	Routing & Data fetching
	HTTP client

---

Project Structure

vite-react-shadcn-starter/
├── src/
│   ├── assets/              # Static assets (images, fonts)
│   ├── components/
│   │   ├── common/          # Shared custom components
│   │   │   └── mode-toggle.tsx
│   │   ├── layout/          # Layout components (Navbar, Sidebar, Footer)
│   │   └── ui/              # Shadcn primitive components
│   │       ├── button.tsx
│   │       ├── card.tsx
│   │       └── ...
│   ├── constants/           # Global constants and enums
│   ├── hooks/
│   │   ├── queries/         # TanStack Query hooks
│   │   ├── use-theme.ts     # Theme management hook
│   │   └── use-mobile.ts
│   ├── lib/
│   │   └── utils.ts         # Utility functions (cn, etc.)
│   ├── routes/              # TanStack Router file-based routes
│   │   ├── __root.tsx       # Root route component
│   │   └── index.tsx        # Home page
│   ├── services/            # Axios instances & API endpoints
│   ├── types/               # Global TypeScript definitions
│   ├── index.css            # Global styles & Tailwind directives
│   ├── main.tsx             # Application entry point
│   └── routeTree.gen.ts     # Auto-generated route tree (DO NOT EDIT)
├── public/                  # Public static files
├── .prettierrc              # Prettier configuration
├── components.json          # Shadcn UI configuration
├── eslint.config.js         # ESLint configuration
├── tsconfig.json            # TypeScript configuration
├── vite.config.ts           # Vite configuration
├── COLLABORATION-GUIDE.md   # Team collaboration guidelines
├── COMMIT-GUIDE.md          # Commit message conventions
└── package.json

---

Getting Started

Prerequisites

Ensure you have the following installed:

• Node.js >= 18.x
• npm >= 9.x or yarn >= 1.22.x or pnpm >= 8.x

Installation

1. Clone the repository

   git clone https://github.com/yourusername/velox-starter-kit.git
   cd velox-starter-kit

2. Install dependencies

   npm install
   # or
   yarn install
   # or
   pnpm install

Development

Start the development server with hot module replacement:

npm run dev

The application will be available at http://localhost:5173

Build

Create a production-ready build:

npm run build

Build output will be in the dist/ directory.

Preview Production Build

Preview the production build locally:

npm run preview

---

Workflow & Collaboration

This project follows a structured Git workflow with strict branch naming and PR conventions.

Branch Structure

main (production)
  └── staging (QA/Testing)
      └── module/{epic} (e.g., module/auth, module/dashboard)
          └── {developer-name}/{epic}/feature/{feature-name}

Branch Naming Conventions

Type	Format	Example
Module Development	{developer-name}/{epic}	alex/dashboard
Feature	{developer-name}/{epic}/feature/{feature-name}	alex/dashboard/feature/analytics-chart
Bugfix	{developer-name}/{epic}/bugfix/{issue-name}	alex/auth/bugfix/login-validation
Component	{developer-name}/components/{component-name}	alex/components/data-table

Pull Request Flow

1. Developer → Module: alex/dashboard → module/dashboard
2. Module → Staging: module/dashboard → staging
3. Staging → Production: staging → main

⛔ Restrictions:

• No direct merges from developer branches to main or staging
• All changes must go through module branches first

For detailed collaboration guidelines, see COLLABORATION-GUIDE.md.

---

Code Quality

Commit Conventions

This project uses Conventional Commits for standardized commit messages:

<type>(<scope>): <subject>

[optional body]

Types:

• feat: New feature
• fix: Bug fix
• ui: UI-only changes
• refactor: Code refactoring
• docs: Documentation
• chore: Build/config changes

Examples:

feat(routes): add user details page with loader
fix(forms): resolve email validation regex
ui(components): update button hover states

For complete commit guidelines, see COMMIT-GUIDE.md.

Linting & Formatting

# Run ESLint
npm run lint

# Format code with Prettier
npm run format

---

Contributing

We welcome contributions! Please follow these steps:

1. Read COLLABORATION-GUIDE.md and COMMIT-GUIDE.md
2. Create a feature branch following naming conventions
3. Make your changes with proper commit messages
4. Submit a PR to the appropriate module branch
5. Wait for code review and approval

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Acknowledgments

• Vite for blazing-fast development experience
• Shadcn UI for beautiful components
• TanStack for powerful routing and data fetching
• The React and TypeScript communities

---

Built with ❤️ using Vite & React

© 2024 Velox Starter Kit. Open Source.