Important

The canonical repository for this project lives on Forgejo: https://code.bhk-itsolutions.com/homeiot/front.git. This GitHub repository is only a mirror and is not the primary git remote.

testts

This template should help get you started developing with Vue 3 in Vite.

Recommended IDE Setup

VS Code + Vue (Official) (and disable Vetur).

Recommended Browser Setup

• Chromium-based browsers (Chrome, Edge, Brave, etc.):
  • Vue.js devtools
  • Turn on Custom Object Formatter in Chrome DevTools
• Firefox:
  • Vue.js devtools
  • Turn on Custom Object Formatter in Firefox DevTools

Type Support for .vue Imports in TS

TypeScript cannot handle type information for .vue imports by default, so we replace the tsc CLI with vue-tsc for type checking. In editors, we need Volar to make the TypeScript language service aware of .vue types.

Customize configuration

See Vite Configuration Reference.

Project Setup

npm install

Environment Variables

Copy the .env.example file to .env and configure the following variables:

• VITE_REST_PORT (default: 2606): Port for the REST API server
• VITE_GRPC_PORT (default: 50051): Port for the gRPC server
• VITE_API_URL (optional): Full URL for the REST API. If not set, the URL will be constructed automatically based on the current hostname and VITE_REST_PORT
• VITE_GRPC_URL (optional): Full URL for the gRPC server. If not set, the URL will be constructed automatically based on the current hostname and VITE_GRPC_PORT
• VITE_API_TIMEOUT (optional, default: 30000): Timeout for API requests in milliseconds. Prevents requests from hanging indefinitely and protects against resource exhaustion attacks
• BASE_URL (optional, default: /): Base URL for the application. Used by Vite router if the app is served from a subdirectory

Example .env file:

VITE_REST_PORT=2606
VITE_GRPC_PORT=50051
VITE_API_URL=http://localhost:2606
VITE_GRPC_URL=http://localhost:50051

Note: Since the web application is hosted on the same server as the REST API, relative paths are used by default for the API URL, which simplifies the configuration and avoids CORS issues.

Compile and Hot-Reload for Development

npm run dev

Type-Check, Compile and Minify for Production

npm run build

Run Unit Tests with Vitest

npm run test:unit

Run in watch mode:

npm run test:unit -- --watch

Run End-to-End Tests with Cypress

Development mode (interactive):

npm run test:e2e:dev

This command:

• Automatically starts the Vite dev server on port 4173
• Waits for the server to be ready
• Opens Cypress Test Runner in interactive mode
• Stops the server when Cypress is closed

Development mode (headless, for quick tests):

npm run test:e2e:dev:headless

Production build (recommended for CI/CD):

npm run build
npm run test:e2e

This runs the end-to-end tests against the production build, which is slower but more representative of the final application.

Run Component Tests with Cypress Component Testing

npx cypress open --component

Visual Regression Tests

Visual regression tests are included in the E2E test suite (cypress/e2e/visual.cy.ts). They capture screenshots of pages and components for comparison.

For more details on testing, see README-TESTS.md.

Performance Optimization

The application uses lazy loading and code splitting for optimal performance:

• Lazy Loading: All route components are loaded on-demand using defineAsyncComponent
• Code Splitting: Vendors, routes, and components are separated into optimized chunks
• Better Caching: Separate vendor chunks ensure better browser caching
• Compression: Automatic gzip and brotli compression for all assets
• Tree-Shaking: Aggressive tree-shaking to remove unused code
• Build Analysis: Visual bundle analyzer to optimize chunk sizes

For more details, see docs/PERFORMANCE.md and docs/BUILD-OPTIMIZATION.md.

Build Analysis

Analyze your bundle size and chunks:

npm run build:analyze

This generates an interactive visualization of your bundle in dist/stats.html.

Progressive Web App (PWA)

The application is configured as a PWA with:

• Service Worker: Automatic caching and offline support
• Manifest: Installable on home screen
• Strategic Caching: Different cache strategies for different resource types
• Auto-update: Automatic updates in the background

Generate PWA icons:

npm run generate:icons

Note: Requires sharp to be installed. If not, use an online service like RealFaviconGenerator to create icon-192.png and icon-512.png in the public/ folder.

Test PWA with HTTPS:

npm run build
npm run preview:https

Note: The browser will show a security warning for the self-signed certificate. This is normal in development - accept the exception to continue.

For more details, see docs/PWA-IMPLEMENTATION.md.

Internationalization (i18n)

The application supports multiple languages:

• French (fr) : Default language
• English (en) : English
• Arabic (ar) : العربية (with RTL support)

Features:

• Automatic browser language detection
• Language persistence in localStorage
• RTL (Right-to-Left) support for Arabic
• Language switcher component

Usage in components:

<template>
  <h1>{{ $t('user.title') }}</h1>
  <button>{{ $t('common.save') }}</button>
</template>

For more details, see docs/I18N.md.

Lint with ESLint

npm run lint

Error Management & Support

The application uses a centralized HTTP client proxy (src/api/http-client.ts) that automatically handles all HTTP errors globally. All requests (including those from the generated OpenAPI client) go through this proxy, ensuring consistent error handling across the application.

Key Features:

• Automatic error normalization: All HTTP errors are automatically normalized and sent to the error store
• Global error handling: No need to manually catch and handle errors in each component
• Token refresh: Automatic token refresh on 401 errors with request retry
• Error logging: All errors are logged with context for debugging

Usage:

For custom HTTP requests, use the centralized client:

import { getHttpClient } from '@/api/config'

const client = getHttpClient()
const response = await client.get('/custom-endpoint')
// Errors are automatically handled and sent to the error store

For requests using the generated OpenAPI API, errors are automatically handled:

import { UsersService } from '@/api'

try {
  const user = await UsersService.getUser({ id: 1 })
} catch (error) {
  // Error is already normalized and sent to error store
  // You can still catch it if you need custom handling
}

HTTP status codes are managed centrally in src/helpers/http-status.ts, providing consistent error handling across the application.

Errors are normalized into three severity levels:

Severity	Typical HTTP Status	User Message Intent
info	401	Inform the user about session or authentication issues
warning	400, 403, 404, 409	Actionable issues the user can usually fix (bad input, forbidden action, missing data)
danger	500+	Critical failures requiring support intervention

Support Procedure

1. Collect context
   • Ask the user for the sequence of actions performed
   • Capture timestamp and browser information if possible
2. Consult in-app history
   • Use useErrorStore().history (available in devtools) to inspect the last 20 normalized errors
   • Note the id, userMessage, techMessage, status, and context
3. Reproduce and diagnose
   • Try to reproduce the issue locally or on a staging environment
   • Check backend logs for the timestamp and request identifier if available
4. Escalate if needed
   • If the issue persists, create a ticket containing the normalized error payload and reproduction steps
   • Include environment variables in use and the API endpoints impacted

Developers can extend this workflow by plugging an external service (Sentry, Datadog…) once VITE_ERROR_WEBHOOK_URL is configured and the connector is enabled.