🚀 Vite React TypeScript Template

Clean Architecture + Atomic Design + GitFlow

A production-ready Vite + React + TypeScript starter template with clean architecture, design system tokens, and enterprise-grade folder structure.

Features • Quick Start • Documentation • Structure • Contributing

---

✨ Features

• ⚡️ Vite 4+ - Lightning fast HMR and optimized builds
• ⚛️ React 18 with TypeScript - Type-safe component development
• 🎨 SCSS Design Tokens - Scalable design system with Spanish conventions
• 🏗️ Atomic Design - Components → Containers → Layouts → Pages
• 📐 BEM Methodology - Consistent CSS naming and organization
• 🔄 GitFlow Ready - Pre-configured branching strategy
• 🎯 Clean Architecture - Separation of concerns with dedicated folders
• 🧪 Testing Ready - Scaffolded test structure (bring your own framework)
• 🌍 i18n Ready - Prepared for multi-language support (en/es/fr)
• 📦 Zero Config - ESLint + Prettier pre-configured
• 🤖 AI-Optimized - GitHub Copilot instructions included

🚀 Quick Start

Using degit (Recommended)

# Clone this template
npx degit Kevinparra535/vite-template-design-sytem-and-gitflow my-project

# Navigate to project
cd my-project

# Install dependencies
npm install

# Start development server
npm run dev

Using GitHub Template

1. Click the "Use this template" button on GitHub
2. Clone your new repository
3. Run npm install && npm run dev

Manual Clone

git clone https://github.com/Kevinparra535/vite-template-design-sytem-and-gitflow.git my-project
cd my-project
rm -rf .git
git init
npm install
npm run dev

📋 Available Scripts

npm run dev      # Start development server with HMR (http://localhost:5173)
npm run build    # Build for production (type-check + build)
npm run preview  # Preview production build locally
npm run lint     # Run ESLint with TypeScript support (--max-warnings 0)

📁 Project Structure

src/
├── assets/              # Static assets organized by type
│   ├── scss/           # SCSS with design tokens
│   │   ├── tokens/     # Design primitives (colors, spacing, typography)
│   │   ├── vendors/    # Third-party styles (bootstrap, breakpoints)
│   │   └── pages/      # Page-specific styles
│   ├── images/         # Images and icons
│   ├── videos/         # Video files
│   └── audios/         # Audio files
│
├── components/         # 🧩 Stateless/Presentational components
│   └── [ComponentName]/
│       ├── Component.tsx
│       ├── Component.md      # Usage documentation
│       └── component.scss    # (optional)
│
├── containers/         # 🎛️ Stateful/Smart components (useState, useReducer)
│
├── layouts/           # 🖼️ Layout wrappers (Header, Footer, Sidebar)
│
├── pages/             # 📄 Page components (Home, Contact, etc.)
│
├── hooks/             # 🪝 Custom React hooks
│
├── contexts/          # 🌐 React Context providers (theme, auth)
│
├── services/          # 🔌 API/external service integrations
│
├── helpers/           # 🛠️ Utility functions
│
├── validations/       # ✅ Form validation schemas (Formik/react-hook-form)
│
├── constants/         # 📌 App constants (regex, config values)
│
├── config/            # ⚙️ Application configuration
│
├── i18n/              # 🌍 Internationalization (en/es/fr)
│   ├── en/
│   ├── es/
│   └── fr/
│
├── routes/            # 🛣️ Routing configuration
│
├── __tests__/         # 🧪 Test files
│
└── __mocks__/         # 🎭 Mock data for testing

Folder Conventions

Folder	Purpose	Example
components/	Pure UI components (no state)	<Button />, <Card />
containers/	Components with state management	<UserProfile />, <DataTable />
layouts/	Page wrappers	<MainLayout />, <DashboardLayout />
pages/	Route-level components	<HomePage />, <AboutPage />
services/	API calls, one file per service	authService.ts, userService.ts
hooks/	Reusable logic	useAuth(), useFetch()
contexts/	Global state	ThemeContext, AuthContext

🎨 Design System

SCSS Tokens (Spanish Convention)

// Colors (src/assets/scss/tokens/colors.scss)
$color-primario: #e6444e;
$color-secundario: #f371b4;
$color-claro: #ffffff;
$color-oscuro: #363636;

// Spacing (src/assets/scss/tokens/spacings.scss)
$space: 10px;
$space_x2: 20px;
$space_x3: 30px;

// Typography (src/assets/scss/tokens/typos.scss)
$Fuente1: 'Poppins', system-ui;
$Fuente2: 'Oswald', system-ui;
$h1: 50px;
$p: 15px;

Using Mixins

@import 'src/assets/scss/index.scss';

.my-button {
  @include botones; // Pre-styled button
  @include titulos($Fuente2); // Auto-uppercase for Oswald
}

BEM Naming Convention

• Files: Plural (buttons.scss)
• Classes: Singular lowercase (.gallery__button)
• Images: Block-relative (hero_background.png)

.gallery {
  &__button {
    &--active {
    }
  }
}

🔄 GitFlow Workflow

This template follows GitFlow branching strategy:

main (production)
  ├── master (integration)
  │   ├── release/* (pre-production)
  │   ├── feature/* (new features)
  │   └── ...
  └── hotfix/* (urgent fixes)

Branch naming:

• feature/user-authentication
• feature/AmazingFeature
• hotfix/critical-bug
• release/v1.0.0

Commit format: Imperative mood

git commit -m 'Add user authentication'
git commit -m 'Fix header responsive issue'

📕 Documentation

For detailed documentation, visit the Wiki:

• 📁 Folder Structure Explained
• 🎨 Style Guide & BEM
• 🔄 GitFlow Strategy
• 🔌 VS Code Extensions

🛠️ Recommended VS Code Extensions

Required:

• ESLint
• Prettier
• GitLens

Recommended:

• GitHub Copilot - AI-assisted coding
• Color Highlight - SCSS token visualization
• Path Intellisense

🧪 Testing (Bring Your Own Framework)

The template includes scaffolded test folders but no framework. Choose your preferred setup:

Jest + React Testing Library:

npm install -D jest @testing-library/react @testing-library/jest-dom

Vitest (Vite-native):

npm install -D vitest @testing-library/react

🌍 Internationalization

Prepared for i18n with src/i18n/ structure. Add your preferred library:

npm install react-i18next i18next

🤝 Contributing

Contributions are what make the open-source community amazing! Any contributions are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

📄 License

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

👤 Author

Kevin Parra Lopez

• GitHub: @Kevinparra535
• Email: kevinparra535@gmail.com

⭐ Show your support

Give a ⭐️ if this project helped you!

---

Made with ❤️ by Kevin Parra Lopez