Skip to main content

​
Frontend Setup

This guide covers setting up the SGIVU frontend for local development, building for production, and troubleshooting common issues.

​
Prerequisites

Before starting, ensure you have the following installed:

​
Required Software

  • Node.js - Compatible with Angular 21 (Node.js 18.19+ or 20.11+ recommended)
  • npm 8+ - Package manager (comes with Node.js)
  • Git - Version control

​
Backend Services

The frontend requires these backend services to be running:
  • sgivu-config - Configuration server
  • sgivu-discovery - Service discovery (Eureka)
  • sgivu-gateway - API gateway and BFF
  • sgivu-auth - Authentication server
You can start all backend services using Docker Compose:
cd infra/compose
docker-compose -f sgivu-docker-compose.yml up -d

​
Installation

​
1. Clone the Repository

git clone <repository-url>
cd apps/frontend/sgivu-frontend

​
2. Install Dependencies

npm install
This will install all dependencies listed in package.json including:
  • Angular framework and CLI
  • Bootstrap and UI libraries
  • Chart.js for visualizations
  • Development tools (ESLint, Prettier, Karma)

​
3. Configure Environment

The default development configuration is in src/environments/environment.development.ts: 
export const environment = {
  production: false,
  apiUrl: 'http://localhost:8080',
  issuer: 'http://sgivu-auth:9000',
  clientId: 'angular-local'
};
If you cannot resolve sgivu-auth hostname (e.g., on Windows without hosts file entry), temporarily change the issuer to:
issuer: 'http://localhost:9000'

​
4. Update Hosts File (Optional)

For better Docker integration, add to your /etc/hosts (Linux/Mac) or C:\Windows\System32\drivers\etc\hosts (Windows): 
127.0.0.1 sgivu-auth
127.0.0.1 sgivu-gateway

​
Development Server

​
Start Development Server

npm start
# or
npm run start
This starts the Angular development server at: The app will automatically reload when you make changes to source files.

​
Development Features

  • Live Reload - Automatic browser refresh on file changes
  • Source Maps - Debug TypeScript in browser DevTools
  • Error Overlay - Build errors displayed in browser
  • Hot Module Replacement - Fast incremental builds

​
Building for Production

​
Standard Build

npm run build
Outputs to dist/sgivu-frontend/ directory.

​
Optimized Production Build

npm run build -- --configuration production
Production optimizations include:
  • Code minification and uglification
  • Tree shaking (removes unused code)
  • Ahead-of-Time (AOT) compilation
  • Bundle optimization and splitting
  • CSS optimization
  • Source map generation (optional)

​
Watch Mode (Development)

npm run watch
Builds and watches for changes without starting a dev server.

​
Testing

​
Unit Tests

Run unit tests with Karma and Jasmine: 
npm test
# or
npm run test
This launches Karma in watch mode and runs tests in Chrome. Test Configuration:
  • Framework: Jasmine
  • Runner: Karma
  • Browser: Chrome (via Puppeteer)
  • Coverage: Enabled with karma-coverage

​
Linting

Check code quality with ESLint: 
npm run lint
This runs ESLint with Angular-specific rules.

​
Code Formatting

Format code with Prettier: 
npx prettier --write "src/**/*.{ts,html,scss,css,json}"
Consider adding Prettier as an npm script in package.json for easier access.

​
Development Workflow

  1. Start Backend Services 
    cd infra/compose
docker-compose -f sgivu-docker-compose.yml up -d
  2. Start Frontend Dev Server 
    cd apps/frontend/sgivu-frontend
npm start
  3. Open Browser
  4. Make Changes
    • Edit files in src/app/
    • Browser automatically reloads
    • Check console for errors
  5. Run Tests 
    npm test
  6. Lint Before Committing 
    npm run lint

​
IDE Recommendations

Visual Studio Code with extensions:
  • Angular Language Service
  • ESLint
  • Prettier - Code formatter
  • Angular Snippets
  • Auto Rename Tag
  • Path Intellisense
WebStorm/IntelliJ IDEA:
  • Built-in Angular support
  • Built-in TypeScript support
  • ESLint integration
  • Prettier integration

​
Troubleshooting

​
401/403 Errors on API Calls

Problem: XHR requests return 401 Unauthorized or 403 Forbidden. Solutions:
  1. Verify apiUrl in environment.development.ts points to sgivu-gateway
  2. Check that sgivu-gateway is running: docker ps | grep sgivu-gateway
  3. Verify session is established: Open DevTools Network tab and check /auth/session response
  4. Clear browser cookies and localStorage
  5. Try logging out and logging back in

​
Issuer/Redirect Mismatch

Problem: OAuth2 redirect fails with issuer mismatch error. Solutions:
  1. Verify issuer matches ISSUER_URL in sgivu-auth configuration
  2. Check application.yml in sgivu-auth for correct issuer URL
  3. Ensure Nginx configuration matches issuer URL
  4. Verify no trailing slashes in issuer URLs

​
Routes Not Found After Deployment

Problem: Direct navigation to routes returns 404 on static hosting. Solutions:
  1. Configure server to serve index.html for all routes
  2. Verify base href in dist/sgivu-frontend/index.html
  3. For Nginx, add rewrite rule: 
    location / {
    try_files $uri $uri/ /index.html;
}
  4. For S3, configure error document to index.html

​
Module Not Found Errors

Problem: Import errors or module not found during build. Solutions:
  1. Delete node_modules and reinstall: 
    rm -rf node_modules package-lock.json
npm install
  2. Clear Angular cache: 
    rm -rf .angular/cache
  3. Verify TypeScript paths in tsconfig.json

​
Port Already in Use

Problem: Port 4200 is already occupied. Solutions:
  1. Use different port: 
    ng serve --port 4201
  2. Kill process using port 4200: 
    # Linux/Mac
lsof -ti:4200 | xargs kill -9

# Windows
netstat -ano | findstr :4200
taskkill /PID <PID> /F

​
CORS Errors

Problem: CORS policy blocks API requests. Solutions:
  1. Verify sgivu-gateway CORS configuration allows http://localhost:4200
  2. Check gateway application.yml for CORS allowed origins
  3. Ensure cookies are included in requests (handled by interceptor)
  4. Verify withCredentials: true in HTTP requests

​
Cannot Resolve Hostname

Problem: Browser cannot resolve sgivu-auth or other service hostnames. Solutions:
  1. Add hostname to /etc/hosts (see Configuration section)
  2. Change issuer to use localhost in development
  3. Verify Docker network configuration if using Docker

​
Environment Configuration

​
Development Environment

Edit src/environments/environment.development.ts: 
export const environment = {
  production: false,
  apiUrl: 'http://localhost:8080',        // Gateway URL
  issuer: 'http://sgivu-auth:9000',       // Auth server
  clientId: 'angular-local'               // OAuth2 client ID
};

​
Production Environment

Edit src/environments/environment.ts: 
export const environment = {
  production: true,
  apiUrl: 'https://api.sgivu.com',        // Production gateway
  issuer: 'https://auth.sgivu.com',       // Production auth
  clientId: 'sgivu-frontend-prod'         // Production client
};
Never commit credentials or secrets to environment.ts files. Use environment-specific configurations and keep production values secure.

​
Next Steps

Architecture

Learn about the frontend architecture and patterns

Features

Explore feature modules and components

Build docs developers (and LLMs) love

Get started for freeTalk to us