Local Development Quickstart

Follow this guide to get the BonardaHR frontend up and running locally on your workstation.

---

Prerequisites

• Node.js: v20.0.0 or higher (Node 22 LTS recommended)
• npm: v10.0.0 or higher
• Backend API: Running locally on http://localhost:8081 (or accessible remotely)

---

Installation & Launch

1. Clone & Install Dependencies

cd frontend
npm install

2. Configure Environment Variables

Create a local .env file based on .env.example:

cp .env.example .env

Default local configuration:

# API Gateway / Backend URL
VITE_API_BASE_URL=http://localhost:8081/api/v1

# Microsoft Entra ID (Azure AD) - Optional for local dev
VITE_AZURE_CLIENT_ID=your-azure-client-id
VITE_AZURE_TENANT_ID=your-azure-tenant-id
VITE_AZURE_REDIRECT_URI=http://localhost:5173/auth/callback

# Application Settings
VITE_APP_NAME=Bonarda HR
VITE_APP_VERSION=0.0.1

# Enable dropdown-based dev login without Azure AD credentials
VITE_DEV_LOGIN_ENABLED=true

tip

Dev Login Mode Setting VITE_DEV_LOGIN_ENABLED=true enables a quick selector on the /login page that allows switching between pre-seeded test employees (HR Admin, Manager, Standard Employee) without authenticating through Microsoft Azure AD.

3. Start the Development Server

npm run dev

The Vite development server will start at http://localhost:5173.

---

Available Scripts

Command	Action
npm run dev	Starts the Vite development server with Hot Module Replacement (HMR)
npm run build	Runs TypeScript compilation check (tsc -b) and bundles production assets into dist/
npm run preview	Spins up a local static server to test the production build locally
npm run test	Executes unit and integration test suite once using Vitest
npm run test:watch	Runs Vitest in interactive watch mode
npm run lint	Runs ESLint 9 across the entire project
npm run format	Runs Prettier to auto-format ts, tsx, json, css, and md files

---

Vite Proxy Configuration

The frontend is pre-configured in vite.config.ts to proxy requests starting with /api to the backend server:

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    proxy: {
      '/api': {
        target: process.env.VITE_API_URL || 'http://localhost:8081',
        changeOrigin: true,
      },
    },
  },
});