Skip to main content

Frontend Local Development Setup

Step-by-step guide to run the Renault Club Bulgaria React frontend locally.

Repository: ivelin1936/renault-club-bulgaria-fe

Prerequisites

The backend must be running before starting the frontend. Follow the BE Setup Guide first.

Prerequisites​

ToolVersionDownload
Node.js20+ LTShttps://nodejs.org
npm10+bundled with Node.js
Git2.xhttps://git-scm.com

1. Clone the Repository​

git clone https://github.com/ivelin1936/renault-club-bulgaria-fe.git
cd renault-club-bulgaria-fe
git checkout master    # main development branch

2. Install Dependencies​

npm install

3. Configure Environment Variables​

cp .env.example .env.local

Edit .env.local:

# Keycloak SSO (must match the Keycloak realm running in Docker)
VITE_KEYCLOAK_URL=http://localhost:8180
VITE_KEYCLOAK_REALM=rcb
VITE_KEYCLOAK_CLIENT_ID=rcb-frontend

# Backend API
VITE_API_BASE_URL=http://localhost:8080
Vite proxy

Vite dev server automatically proxies /api → http://localhost:8080 (configured in vite.config.ts). You only need VITE_API_BASE_URL for direct API calls outside the proxy.

4. Run the Development Server​

npm run dev

Frontend starts on http://localhost:5173

Open your browser and click "Login" — it will redirect to Keycloak at http://localhost:8180.

5. Available Scripts​

CommandDescription
npm run devStart Vite dev server (port 5173)
npm run buildProduction build (outputs to dist/)
npm run lintESLint check
npm run type-checkTypeScript type check
npm run testVitest unit tests
npm run test:coverageUnit tests with coverage report
npm run e2ePlaywright E2E tests (backend + frontend must be running)

6. Tech Stack​

ConcernTechnology
FrameworkReact 19
LanguageTypeScript 5 — strict mode
BuildVite 6 — instant HMR, Rollup prod build
UIMaterial UI v6 — sx prop, theme tokens
RoutingReact Router v7 — createBrowserRouter, loaders
Server stateTanStack Query v5 — useQuery, useMutation
Client stateZustand v5 — UI/client state only
FormsReact Hook Form v7 + Zod (schema + z.infer<>)
Auth@react-keycloak/web + keycloak-js → JWT Bearer token
Custom auth UIKeycloakify v11 — React components in Keycloak login UI
HTTP clientAxios — Bearer interceptor, 401 → keycloak.login()
Unit testsVitest + React Testing Library + MSW v2
E2E testsPlaywright
LintingESLint 9 flat config + @typescript-eslint
FormattingPrettier 3

7. Project Structure​

src/
├── app/                    # App shell: router, providers, Keycloak init
│   ├── App.tsx             # Root: ReactKeycloakProvider > QueryClientProvider > ThemeProvider > RouterProvider
│   ├── keycloak.ts         # Keycloak instance (VITE_KEYCLOAK_URL/REALM/CLIENT_ID)
│   └── router.tsx          # createBrowserRouter — all routes
│
├── features/               # One folder per domain
│   └── {feature}/
│       ├── api/            # {feature}.api.ts (axios calls) + {feature}.queries.ts (TanStack hooks)
│       ├── components/     # Feature UI components
│       ├── hooks/          # Feature-specific custom hooks
│       ├── stores/         # Zustand slice
│       ├── types/          # TypeScript types
│       └── index.ts        # Public API
│
├── shared/                 # Cross-feature reusables
│   ├── components/         # Generic UI (Button, Modal, DataTable)
│   ├── hooks/              # Generic hooks (useAuth, useDebounce)
│   ├── stores/             # Global Zustand stores (auth, notifications)
│   ├── utils/              # apiClient.ts (Axios + Bearer), formatDate, parseError
│
├── theme/                  # MUI createTheme — primary #fcd434, secondary #1a1a1a
│
├── keycloak-theme/         # Keycloakify v11 — KcApp, Login, Register, etc.
│
└── test/                   # Vitest setup, renderWithProviders, MSW handlers

8. Routes​

PathDescription
/Homepage
/eventsEvents list
/events/:idEvent detail + comments
/newsNews list
/news/:idNews detail + comments
/galleryPhoto galleries
/campaignsClub campaigns
/carsGarage / car management
/membershipMembership card
/partnersClub partners
/assistanceClub assistance (Leaflet map)
/profileUser profile
/adminAdmin panel

9. Features​

Authentication​

  • Keycloak SSO with PKCE flow
  • JWT Bearer token injected via Axios interceptor
  • Token refresh via @react-keycloak/web
  • Custom login/register UI via Keycloakify v11

Theme​

  • MUI v6 with Renault brand colors: primary #fcd434 (yellow), secondary #1a1a1a (dark)
  • Dark/light mode support

Events​

  • Paginated card grid with status chips (UPCOMING / ACTIVE / FINISHED / CANCELLED)
  • Event detail with apply button (authenticated users only)
  • Comment section with 2-level nesting

Garage​

  • Personal car list with maintenance alerts panel
  • Vehicle Checks Modal — calls backend GET /api/v1/garage/{carId}/checks
  • Shows МВР, АПИ, ГО, Виньетка check status

Club Assistance​

  • Leaflet map (OpenStreetMap tiles) showing nearby members
  • Location sharing toggle + radius slider (5/10/25/50 km)
  • 429 rate limit → Snackbar; 403 (no membership) → banner

10. Troubleshooting​

ProblemSolution
Blank page after loginCheck DevTools → Console for Keycloak errors; verify VITE_KEYCLOAK_URL
401 on API callsToken may have expired; Keycloak must be running
/api calls fail with CORSBackend must be running on localhost:8080
npm install failsUse Node.js 20+ LTS: node -v
Keycloak login loopVerify VITE_KEYCLOAK_CLIENT_ID=rcb-frontend matches Keycloak realm config
Map not loadingCheck browser console; Leaflet CSS must be imported in main.tsx