Angular Boilerplate Developer Guide

This guide provides a detailed step-by-step approach to setting up, configuring, and utilizing the Angular boilerplate. It covers project initialization, folder organization, logging, Docker usage, unit testing, and CI/CD integration.

1. Overview

This Angular boilerplate is designed to streamline development by integrating essential configurations for scalability and maintainability. Key features include:

• Service Discovery (SD): Dynamic API endpoint resolution.
• Logger Integration: Configurable logging with multiple log levels.
• Config Loader: Environment-based configuration management.
• GitLab CI/CD: Automated build, test, and deployment pipelines.
• Dockerization: Production-ready Docker configuration.
• Unit Testing: Jasmine and Karma integrated with sample test cases.

2. Getting Started

2.1 Prerequisites

Before starting, ensure you have the following installed:

• Node.js (Latest LTS version) - Download
• Angular CLI - Install globally using:

  npm install -g @angular/cli

• Docker (for containerized deployment) - Install Docker
• Git (for version control) - Download Git

2.2 Project Setup

1. Clone the Repository and Install Dependencies:

   git clone https://git.tetherfi.com/sachinikumarathunga/angular-boilerplate-creation.git
   cd angular-boilerplate-creation
   npm install

2. Run the Development Server:

   ng serve

   Then, open your browser at http://localhost:4200.

3. Build the Application:

   ng build --configuration=production

3. Folder Structure & Usage

A well-structured project ensures maintainability. Below is the recommended folder organization:

src/
├── app/
|   ├── auth/
|   |   ├──sign-in/
│   ├── core/                # Core services, guards, interceptors, models, and state management
│   │   ├── guard/
│   │   ├── interceptors/
│   │   ├── models/
│   │   ├── services/
│   │   └── state/
│   ├── pages/            # Feature-specific modules and components
|   ├── error/
|   |   ├── access-denied
|   |   ├── internal-server-error
|   |   ├── not-found
│   └── shared/              # Reusable components, directives, and pipes
│       ├── components/
│       ├── directives/
│       └── pipes/
├── assets/                  # Static files (images, fonts, etc.)
└── environments/            # Environment-specific configurations

Guidelines:

• Core: Contains essential services such as service discovery, logging, and config loader.
• Features: Encapsulate independent modules with their own components and services.
• Shared: Houses reusable UI components, directives, and pipes.
• Environments: Manage configurations for different deployment environments.

4. Configuration Management

4.1 Environment Configurations

• Modify environment.ts for development and environment.prod.ts for production.
• Example:

  export const environment = {
    production: false,
    apiUrl: 'https://api-dev.example.com',
    logLevel: 'debug'
  };

4.2 Logger Configuration & Management

Installation

npm install ngx-logger

Configuration

import { LoggerModule, NgxLoggerLevel } from 'ngx-logger';
@NgModule({
  imports: [
    LoggerModule.forRoot({ level: NgxLoggerLevel.DEBUG, serverLoggingUrl: '/api/logs' })
  ]
})
export class AppModule { }

Usage

import { NGXLogger } from 'ngx-logger';
constructor(private logger: NGXLogger) {
  this.logger.debug('Debug message');
  this.logger.error('Error message');
}

Log Management

• Logs appear in the console in development.
• In production, configure server-side logging for analysis.

5. Dockerization

5.1 Dockerfile

FROM node:latest as builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install --force
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist/angular-boilerplate /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

5.2 docker-compose

version: '3'
services:
  angular-app:
    build: .
    ports:
      - "80:80"
    restart: always

6. Unit Testing

6.1 Setup

npm install --save-dev jasmine karma

6.2 Running Tests

ng test

6.3 Writing Test Specs

Create a test spec file (component.spec.ts) for a component/service:

import { ComponentFixture, TestBed } from '@angular/core/testing';
import { MyComponent } from './my-component.component';

describe('MyComponent', () => {
  let component: MyComponent;
  let fixture: ComponentFixture<MyComponent>;

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      declarations: [MyComponent]
    }).compileComponents();
  });

  beforeEach(() => {
    fixture = TestBed.createComponent(MyComponent);
    component = fixture.componentInstance;
    fixture.detectChanges();
  });

  it('should create', () => {
    expect(component).toBeTruthy();
  });
});

7. GitLab CI/CD Integration

7.1 CI/CD Pipeline

stages:
  - build
  - test
  - deploy

build:
  script:
    - npm install
    - npm run build

test:
  script:
    - npm run lint
    - npm run test

deploy:
  script:
    - echo "Deploying application..."

8. Build & Development Scripts

To streamline development, the following scripts are available:

• Cleaning Tasks:

  • build:clean: Removes build artifacts.
  • test:clean: Deletes test coverage reports.
  • analyze:clean: Removes analysis results.
  • clean:all: Runs all cleaning tasks together.

• Linting & Formatting:

  • lint:js: Runs ESLint on JavaScript files.
  • lint:css: Lints CSS styles.
  • lint:eslint:fix: Fixes ESLint warnings/errors automatically.
  • prettify: Formats code using Prettier.

• Testing Enhancements:

  • test: Runs unit tests with coverage.
  • test:watch: Watches for file changes and reruns tests automatically.
  • test:clean: Cleans up test reports.

• Analysis & Setup:

  • analyze: Runs bundle analysis for performance optimization.
  • setup: Initializes the project with required dependencies.
  • npmcheckversion: Ensures correct Node.js and NPM versions are installed.

• Build & Run Commands:

  • start: Runs the development server (ng serve).
  • build: Builds the application for production.
  • start:prod: Runs the production build.
  • watch: Builds the app and watches for file changes.
  • serve:ssr:tetherfi-angular-boilerplate: Runs the server-side rendering build.

9. Contribution Guidelines

To contribute:

1. Fork and Branch: Create a new branch for your feature or bug fix.
2. Coding Standards: Follow the project's best practices.
3. Testing: Run tests locally before submitting a pull request.
4. Pull Request: Provide a clear description of changes.

10. Additional Resources & Troubleshooting

• Angular Documentation: https://angular.io/docs
• Docker Documentation: https://docs.docker.com/
• Logging Best Practices: Explore centralized logging solutions.
• CI/CD Tips: Review GitLab’s CI/CD guides.

This boilerplate serves as a strong foundation for scalable Angular development with best practices. 🚀