A production-ready React starter template powered by modern web technologies and best practices.
- Overview
- Features
- Tech Stack
- Project Structure
- Getting Started
- Workflow & Collaboration
- Code Quality
- Contributing
- License
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
- 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
- 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
- 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
- React Hook Form - Performant form handling
- Zod - TypeScript-first schema validation
- 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
| Technology | Purpose |
|---|---|
 |
Build tool & dev server |
 |
UI library |
 |
Type safety |
 |
Styling |
 |
Routing & Data fetching |
 |
HTTP client |
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
Ensure you have the following installed:
- Node.js >= 18.x
- npm >= 9.x or yarn >= 1.22.x or pnpm >= 8.x
-
Clone the repository
git clone https://github.com/yourusername/velox-starter-kit.git cd velox-starter-kit -
Install dependencies
npm install # or yarn install # or pnpm install
Start the development server with hot module replacement:
npm run devThe application will be available at http://localhost:5173
Create a production-ready build:
npm run buildBuild output will be in the dist/ directory.
Preview the production build locally:
npm run previewThis project follows a structured Git workflow with strict branch naming and PR conventions.
main (production)
└── staging (QA/Testing)
└── module/{epic} (e.g., module/auth, module/dashboard)
└── {developer-name}/{epic}/feature/{feature-name}
| 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 |
- Developer → Module:
alex/dashboard→module/dashboard - Module → Staging:
module/dashboard→staging - Staging → Production:
staging→main
⛔ Restrictions:
- No direct merges from developer branches to
mainorstaging - All changes must go through module branches first
For detailed collaboration guidelines, see COLLABORATION-GUIDE.md.
This project uses Conventional Commits for standardized commit messages:
<type>(<scope>): <subject>
[optional body]
Types:
feat: New featurefix: Bug fixui: UI-only changesrefactor: Code refactoringdocs: Documentationchore: Build/config changes
Examples:
feat(routes): add user details page with loader
fix(forms): resolve email validation regex
ui(components): update button hover statesFor complete commit guidelines, see COMMIT-GUIDE.md.
# Run ESLint
npm run lint
# Format code with Prettier
npm run formatWe welcome contributions! Please follow these steps:
- Read COLLABORATION-GUIDE.md and COMMIT-GUIDE.md
- Create a feature branch following naming conventions
- Make your changes with proper commit messages
- Submit a PR to the appropriate module branch
- Wait for code review and approval
This project is licensed under the MIT License - see the LICENSE file for details.
- 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.