> For the complete documentation index, see [llms.txt](https://kdongs.gitbook.io/kdocs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kdongs.gitbook.io/kdocs/angular/basics.md).

# Basics

{% hint style="info" %}
Up to date with **Angular v19/20.**
{% endhint %}

## Basic Fundamentals & Details

A framework for building SPA.

Written in Typescript.

#### **Fundamental Concepts**

**Components**

* Define Views, which are sets of screen elements that Angular can choose among and modify according to the logic and data.
* Use Services, which provide background functionality not directly related to views. (like data fetching)
  * These services can be injected into components as dependencies, making the code modular, reusable and efficient.
* Components and Services are classes marked with decorators, which provide metadata to Angular on how to use them.
  * For Components, it associates it with the template that defines the component View.
  * For Services, it provides information Angular needs to make it available to components through Dependency Injection.

**Templates**

* They combine HTML with Angular markup to modify the elements before being displayed.
* Template Directives, provides program logic in the HTML.
* Binding markup, connects your application data and the DOM.
  * Event biding, lets your application respond to user input by updating the application data. (DOM -> Application)
  * Property biding, lets you interpolate values that are computed from your application data into the HTML. (Application -> DOM)
  * There is also two-way binding.
* Templates can also use Pipes, to transform values for display.
  * Angular provides common pipes for transformation,
  * But you can define your own pipes.

**Services**

* Service classes are created for data or logic that isn't associated with a specific View, and that you want to share across components.
* A service class is immediately preceded by `@Injectable()` decorator.

#### **Versioning**

* `AngularJS` is the version 1 of angular, and it is not used anymore.
* `Angular 2`, was a complete re-write because of some fundamental flaws in the way it was written.
  * Angular 3 was skipped.
  * After Angular 2, came the major versions 4, 5, 6, ..., up until new latest.
* Each 6 months a new major version is released.
  * Changes are pretty minor.
  * Angular is very backward compatible.
  * It hasnt changed that much since Angular 2.

*Version 1 of angular is refered as AngularJS, and Version 2+ is usually only refered as Angular.*

## Change Detection

Is the process by which Angular determines if something changed in a Template, and if any DOM needs to be updated.

### `Zone.js` Strategy

Angular will wrap the entire application tree with `Zone`, which is a feature provided by `Zone.js`, and it informs Angular about potential events going on on the page that could potentially lead to changes that should be reflected on the screen.

* Changes are detected automatically.
* UI is updated automatically.
* The downsides are that performance of the app could be better & bundle size is increased.
  * Since Angular has to keep listening to changes all the time.
* At a high level, Angular walks your components from top to bottom, looking for changes.
* Angular runs its change detection mechanims periodically so that changes to the data model are reflected in the view.

{% hint style="info" %}
*Change detection will only run, if there was some event listener set up for the element - for instance in a button click.*

*It will NOT run for any random event happening anywhere on the page if no one is listening.*
{% endhint %}

#### **How it works**

1. If a user clicks a button, change detection process starts and visits all components in the entire application, no matter where that click ocurred.
2. Then takes a look at all the templates there, all the template bindings (property bindings, string interpolations, etc).
3. And Angular cheks whether that binding now produces a new value that is different from what it was visible before.
4. If that is the case, Angular updates the real DOM with that new value.

#### How to be more effitient with `Zone`

* Avoid writing complex or expensive calculations in `Template`. They should be simple and straightforward.
* Avoid calling functions on `string interpolations`.
* `Getters`, `functions` that are directly used in Templates should not have expensive calculations.
* Avoid [Broken mention](broken://pages/iOwon2sk8JFv5zGDKCp8#zone-pollution).

### `OnPush` Strategy

* You can enable on a per component basis.
* To make sure that change detection potentially runs less often for the given component.
* Enable it in [`@Component` more info](broken://pages/vdGLt9Sr3XV5jFeKzgA3).
* It is more efficient since it limits the amount of events or things that could trigger change detection.

```typescript
@Component({
    changeDetection: ChangeDetectionStrategy.OnPush
})
...
```

#### **How it works**

* It tells Angular that the component for which it was enabled will only ever change:
  * Because some event occurred inside of this sub Component tree, or
  * Because an input value changed in the Component where `OnPush` was set, or
  * Because of a manually triggered change detection.
* Change detection will run for the Component and all of its child components.
* **But `OnPush` does not restrict events from affecting other components.**
  * All it does is makes sure that the component with it dont get evaluated unnecessarily.
  * But if an event occurs in the component, then of course, the parent Components of this component will be notified all the way up to the App component, and this will lead to the entire tree being checked.
  * **The only way of changing that and improving the application is to go to the place where change detection should be avoided, and not in the place where the event occurs.**

#### **Manually triggering**

{% hint style="info" %}
Ex.: If you are using a Service - *that holds data with normal variables* - to share data between two `OnPush` components, the views in these components might not be updated with new data, because technically no `event` or `input` was triggered or changed.
{% endhint %}

* To deal with the situation above, you will have to either write the Service using `Signals`, or you can make `manual triggering` of the change detection.
* To trigger manually:
  * Inject the `ChangeDetectorRef` service and call `markForCheck()`.
  * But you must call it in the Component that should be checked, and NOT in the Service when the data changed.
    * *You will need to rewrite the Service to use an Observable, so that the Components get notified of changes.*

**Using `async` pipe. The `async` pipe will handle the `subscription`, `unsubscription` and `markForCheck` automatically.**

```typescript
@Component({
    import: [AsyncPipe],
    template: ` @for (item of data$ | async; track $index) { ... } `,
})
export class Component {
    private theService = inject(TheService);
    data$ = this.theService.data$;
}
```

Or in a more verbose way:

```typescript
@Component({
    template: `
        @for (item of dataFromService; track $index) {
            ...
        }
    `
})
export class Component {
    private changeDetectorRef = inject(ChangeDetectorRef);
    private theService = inject(TheService);
    private subscription;

    dataFromService = [];

    ...
    ngOnInit() {
        subscription = this.theService.data$.subscribe((newData) => {
            this.dataFromService = newData;
            this.changeDetectorRef.markForCheck();
        })
    }

    ngOnDestroy() {
        this.subscription.unsubscribe();
    }
    ...
}
```

<br>

## Angular CLI (Command-Line Interface)

{% embed url="<https://angular.dev/tools/cli>" %}
guide/cli
{% endembed %}

{% embed url="<https://github.com/angular/angular-cli/wiki>" %}

### **Installing Globally**

```bash
npm install -g @angular/cli
```

### **Basic Commands**

{% embed url="<https://angular.dev/cli>" %}
cli/commands
{% endembed %}

*You can find and change what some of `ng` commands executes in the project `angular.json` file.*

* `--help`: Use it on any command to check more parameters.
* `--dry-run`: To emulate the command without actually doing it.

### **Creating a Project**

```bash
ng new <project-name>
```

#### **Some additional creation options (Flags)**

* `--standalone false`: To create a project using `NgModules` instead of `Standalone` components.
* `--routing false`: To avoid creating initial routing setup.

### **Running the Project**

```bash
ng serve
```

#### **Some additional running options (Flags)**

* `--open`: To automatically open the Browser.

### **Building the Project**

`ng build` will use `production` configurations unless configured otherwise.

It will also use optimization features like:

* Ahead of Time (AOT)
* Bundling
* Minification
* Mangling
* Dead code elimination

```bash
# Old way of building for production
ng build --prod

# Recent versions don't require the `--prod` flag
ng build
```

#### **Some additional building options (Flags)**

* `--configuration`: To choose different configuration options/environments to use when building.
  * Example `ng build --configuration development`.

Check [#environments](#environments "mention") for more info over Angular environments.

### **Lint**

Will use `tslint.json` file to run a linter on the project and catch lint errors.

```bash
ng lint
```

### `angular.json`

{% embed url="<https://angular.dev/reference/configs/workspace-config>" %}
Workspace config
{% endembed %}

```json
{
    ...
    "projects": {
        "angular-config": {
            ...
            "sourceRoot": "src",   // Default root folder for the source code
            "prefix": "app",       // Default prefix for the Application
            "architect": {         // Default configuration of different commands that can be executed
                "build": {         // The build command
                    ...
                    "options": {   // Default options executed by the build command
                        ...
                    }
                },
                ...
            }
        }
    }
}
```

### Environments

{% embed url="<https://angular.dev/tools/cli/environments>" %}
cli/environments
{% endembed %}

You may create the `environments` folder for environment variables with:

```bash
ng generate environments
```

```bash
my-app/src/environments
├── environment.development.ts
├── environment.staging.ts
# Contains the default environment settings
└── environment.ts
```

Each file will consist of a base:

```typescript
import Class from 'file'

export const environment = {
    production: true | false,

    // Additional variables
    var_name: 'value',
    ...
    
    /**
     * You may also define variable with class definitions, so that you can use different classes for different envirnoments.
     * This helps for Dependency Injection depending on the environment.
     */
    other_var: Class
};
```

Configure in the `angular.json` what file will be used by default in `ng serve` or `ng build`.