Frontend Setup

Setup and development workflow for the SGIVU Angular frontend

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:

• URL: http://localhost:4200
• Hot Reload: Enabled by default
• Source Maps: Enabled for debugging

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

Recommended 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

   • Navigate to http://localhost:4200
   • Login credentials depend on your sgivu-auth configuration

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