Installation Guide

This comprehensive guide covers everything you need to know about installing, configuring, and deploying Air Tracker.

System Requirements

Required Software

Node.js

Version: 18.x or higher (LTS recommended)Air Tracker is tested with Node.js v24.13.1 but any version 18.x+ should work.

Package Manager

Options: npm (7+), yarn (1.22+), or pnpm (8+)npm comes bundled with Node.js.

TypeScript

Version: ~5.9.2Automatically installed as a dev dependency.

Angular CLI

Version: ^20.2.2Optional but recommended for development.

System Specifications

OS: Windows 10+, macOS 10.15+, or Linux (Ubuntu 20.04+)
RAM: Minimum 4GB (8GB recommended for development)
Disk Space: At least 500MB for node_modules and build artifacts
Browser: Modern browser with ES2022 support (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)

Installation Steps

1. Install Node.js

If you don’t have Node.js installed:

macOS Installation

Using Homebrew:

brew install node

Using nvm (recommended):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

Windows Installation

Using official installer:

Download from nodejs.org
Run the installer
Verify installation:

node --version
npm --version

Using nvm-windows:

nvm install 20
nvm use 20

Linux Installation

Using package manager (Ubuntu/Debian):

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Using nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

2. Clone the Repository

git clone <repository-url>
cd air-tracker-frontend

3. Install Dependencies

npm install

This installs all dependencies defined in package.json, including: Core Dependencies:

@angular/core (^20.2.0) - Angular framework
@angular/common (^20.2.0) - Common Angular APIs
@angular/router (^20.2.0) - Routing and navigation
@angular/forms (^20.2.0) - Form handling
@angular/material (^20.2.14) - Material Design components
leaflet (^1.9.4) - Interactive maps
leaflet-moving-rotated-marker (^0.0.1) - Animated flight markers
rxjs (~7.8.0) - Reactive programming

Development Dependencies:

@angular/cli (^20.2.2) - Angular command-line tools
typescript (~5.9.2) - TypeScript compiler
jasmine-core (~5.9.0) - Testing framework
karma (~6.4.0) - Test runner
eslint (^9.39.1) - Code linting

The installation typically takes 2-5 minutes depending on your internet connection and system performance.

Environment Configuration

Development Environment

The development environment configuration is located at src/environments/environment.ts:

export const environment = {
  production: false,
  apiBaseUrl: 'http://localhost:3000/api',
  features: {
    enableFavorites: true,
    enableStats: true,
  },
} as const;

Configuration Options:

production: Set to false for development mode
apiBaseUrl: Backend API endpoint (default: http://localhost:3000/api)
features.enableFavorites: Enable/disable favorite flights feature
features.enableStats: Enable/disable statistics display

Production Environment

The production environment configuration is at src/environments/environment.production.ts:

export const environment = {
  production: true,
  apiBaseUrl: '/api',
  features: {
    enableFavorites: true,
    enableStats: true,
  },
} as const;

In production, the apiBaseUrl is set to /api (relative path), which assumes your API is served from the same domain as your frontend.

Custom Configuration

To customize the configuration:

Copy the environment file:

cp src/environments/environment.ts src/environments/environment.local.ts

Update your values:

export const environment = {
  production: false,
  apiBaseUrl: 'https://your-api-domain.com/api',
  features: {
    enableFavorites: true,
    enableStats: false,  // Disable stats
  },
} as const;

Update angular.json to use your custom environment (optional)

Running the Application

Development Server

Start the development server:

npm start

The application will be available at http://localhost:4200/. Development Server Features:

Hot Module Replacement (HMR)
Source maps for debugging
No optimization for faster builds
Detailed error messages

Production Build

Build the application for production:

npm run build

This runs ng build with the production configuration, which includes:

Environment replacement: Swaps environment.ts with environment.production.ts
Optimization: Minification, tree-shaking, and dead code elimination
Output hashing: Cache-busting file names
AOT compilation: Ahead-of-time compilation for faster runtime

Build Configuration:

"budgets": [
  {
    "type": "initial",
    "maximumWarning": "1MB",
    "maximumError": "2MB"
  },
  {
    "type": "anyComponentStyle",
    "maximumWarning": "4kB",
    "maximumError": "8kB"
  }
]

Build artifacts will be stored in the dist/air-tracker-frontend/browser/ directory.

The production build is optimized for performance and produces significantly smaller bundle sizes compared to development builds.

Running Tests

Unit Tests

Run unit tests with Karma:

npm test

This launches Karma test runner with:

Jasmine testing framework
Chrome headless browser
Code coverage reports
Watch mode for continuous testing

Linting

Run ESLint to check code quality:

npm run lint

The project uses:

ESLint 9.39.1
angular-eslint 21.0.1
TypeScript ESLint 8.46.4

Common Installation Issues

Node version mismatch

Problem: “The engine ‘node’ is incompatible with this module”Solution:

# Check your Node.js version
node --version

# If below 18.x, upgrade using nvm
nvm install 20
nvm use 20

# Or download from nodejs.org

npm install fails with EACCES

Problem: Permission errors during npm installSolution:

# Option 1: Use nvm (recommended)
nvm install 20
nvm use 20

# Option 2: Fix npm permissions
sudo chown -R $USER:$(id -gn $USER) ~/.npm
sudo chown -R $USER:$(id -gn $USER) ~/.config

# Never use sudo with npm install!

Port 4200 already in use

Problem: “Port 4200 is already in use”Solution:

# Option 1: Use a different port
ng serve --port 4300

# Option 2: Kill the process using port 4200
# macOS/Linux:
lsof -ti:4200 | xargs kill -9

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

Leaflet CSS not loading

Problem: Map tiles not displaying correctlySolution: Verify that Leaflet CSS is included in angular.json:

"styles": [
  "src/styles.scss",
  "node_modules/leaflet/dist/leaflet.css"
]

Restart the dev server after making changes to angular.json.

TypeScript compilation errors

Problem: Strict mode TypeScript errorsSolution: The project uses strict TypeScript settings:

"strict": true,
"noImplicitOverride": true,
"noPropertyAccessFromIndexSignature": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true

Ensure your code follows these strict rules. Common fixes:

Add explicit return types
Handle all code paths in functions
Use proper type annotations
Avoid implicit any types

Backend API connection fails

Problem: “Failed to fetch” or CORS errorsSolution:

Check API is running:
```
curl http://localhost:3000/api/health
```

Update environment.ts:

apiBaseUrl: 'http://localhost:3000/api'

Configure CORS on your backend to allow http://localhost:4200

Use proxy configuration (create proxy.conf.json):

{
  "/api": {
    "target": "http://localhost:3000",
    "secure": false,
    "changeOrigin": true
  }
}

Then run:

ng serve --proxy-config proxy.conf.json

Build Optimization

Bundle Analysis

Analyze your bundle size:

npm run build -- --stats-json
cd dist/air-tracker-frontend/browser
npx webpack-bundle-analyzer stats.json

Performance Tips

Reduce Bundle Size

Use lazy loading for routes
Import only necessary Angular Material modules
Enable tree-shaking in production
Compress assets with gzip/brotli

Deployment

Static Hosting

Deploy to static hosting services:

# Install Netlify CLI
npm install -g netlify-cli

# Build and deploy
npm run build
netlify deploy --prod --dir=dist/air-tracker-frontend/browser

Docker Deployment

Create a Dockerfile:

# Build stage
FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM nginx:alpine
COPY --from=build /app/dist/air-tracker-frontend/browser /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Build and run:

docker build -t air-tracker .
docker run -p 80:80 air-tracker

Additional Resources

Getting Help

If you encounter issues not covered in this guide:

Check the GitHub Issues
Review Angular CLI documentation
Search Stack Overflow with the angular tag
Join the Angular community on Discord

Keep your dependencies up to date by running npm outdated regularly and updating with npm update.

Getting Started

Features

Architecture

Installation

Installation Guide

System Requirements

Required Software

Node.js

Package Manager

TypeScript

Angular CLI

System Specifications

Installation Steps

1. Install Node.js

2. Clone the Repository

3. Install Dependencies

Environment Configuration

Development Environment

Production Environment

Custom Configuration

Running the Application

Development Server

Production Build

Running Tests

Unit Tests

Linting

Common Installation Issues

Build Optimization

Bundle Analysis

Performance Tips

Reduce Bundle Size

Deployment

Static Hosting

Docker Deployment

Additional Resources

Getting Help

Build docs developers (and LLMs) love

Getting Started

Features

Architecture

​Installation Guide

​System Requirements

​Required Software

Node.js

Package Manager

TypeScript

Angular CLI

​System Specifications

​Installation Steps

​1. Install Node.js

​2. Clone the Repository

​3. Install Dependencies

​Environment Configuration

​Development Environment

​Production Environment

​Custom Configuration

​Running the Application

​Development Server

​Production Build

​Running Tests

​Unit Tests

​Linting

​Common Installation Issues

​Build Optimization

​Bundle Analysis

​Performance Tips

Reduce Bundle Size

​Deployment

​Static Hosting

​Docker Deployment

​Additional Resources

​Getting Help

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Required Software

System Specifications

Installation Steps

1. Install Node.js

2. Clone the Repository

3. Install Dependencies

Environment Configuration

Development Environment

Production Environment

Custom Configuration

Running the Application

Development Server

Production Build

Running Tests

Unit Tests

Linting

Common Installation Issues

Build Optimization

Bundle Analysis

Performance Tips

Deployment

Static Hosting

Docker Deployment

Additional Resources

Getting Help