Forem: Mauricio Arce Torrez

[Boost]

Mauricio Arce Torrez — Tue, 29 Jul 2025 17:17:55 +0000

Mauricio Arce Torrez

Jul 29 '25

My Angular Style Guide & Coding Conventions

#angular #webdev #programming #typescript

Comments

13 min read

My Angular Style Guide & Coding Conventions

Mauricio Arce Torrez — Tue, 29 Jul 2025 17:13:00 +0000

This document outlines the coding style and best practices for Angular development within my projects. It is inspired by the Angular Style Guide, and my experience working with Angular, so it is heavily opinionated. Adhering to these guidelines ensures consistency, readability, maintainability, and optimal performance across my codebase.

1. General Principles & Best Practices

1.1 Prefer Declarative Code

Rule: Strive for declarative code over imperative code.

Explanation: Declarative code describes what should be done, rather than how it should be done. This leads to more readable, predictable, and maintainable code. This principle encourages immutability, small components, and leveraging Angular's reactive features.

Examples:

Good: Using signals or RxJS operators to transform data.
Bad: Manually manipulating DOM elements or updating state in multiple places.

1.2 One Concept Per File

Rule: Each file should generally contain a single Angular concept (e.g., one component, one directive, one pipe, one service, one model/interface).

Explanation: This promotes modularity, easier navigation, and better reusability. This rule can be relaxed if the additional element is used only within that file (not exported) and does not significantly increase the file size or complexity.

Example:

// Good: app.component.ts
@Component({...})
export class AppComponent {}

// Good: user.model.ts
export interface User { /* ... */ }

// Acceptable exception: If User is only used in MyComponent and is small.
// my-component.ts
interface User { name: string, /* ... */ }

@Component({
  standalone: true,
  template: `{{ user.name }}`,
})
export class MyComponent {
  protected readonly user: User = { name: "...", /* ... */ };
}

1.3 Default to readonly Properties

Rule: Component properties should be declared readonly by default where possible.

Explanation: Using readonly encourages immutability and prevents accidental imperative changes to properties, making state management more predictable and debugging easier.

Example:

// Good
export class MyComponent {
  readonly title = 'My App';
  readonly items = signal<string[]>([]); // Signal is already immutable by nature
}

// Bad (if 'title' is not intended to be changed imperatively)
export class MyComponent {
  title = 'My App';
}

2. Angular Core Features

2.1 Use Built-in Control Flow

Rule: Discontinue the use of structural directives like *ngIf, *ngFor, and *ngSwitch. Always use Angular's new built-in control flow syntax.

Explanation: The new control flow offers improved performance, better type checking, and a more intuitive syntax.

Examples:

<!-- Good: @if -->
@if (user) {
  <p>Welcome, {{ user.name }}!</p>
} @else {
  <p>Please log in.</p>
}

<!-- Good: @for -->
@for (item of items; track item.id) {
  <li>{{ item.name }}</li>
} @empty {
  <p>No items found.</p>
}

<!-- Good: @switch -->
@switch (status) {
  @case ('loading') {
    <p>Loading...</p>
  }
  @case ('success') {
    <p>Data loaded successfully!</p>
  }
  @default {
    <p>Unknown status.</p>
  }
}

2.2 Always Use track Key in for Control Flow

Rule: Always provide a track key in for loops. If iterating over primitive values, use the value directly. If iterating over objects, use a unique, primitive property of the object (e.g., id). Avoid using the object reference itself, as it can cause unnecessary re-rendering.

Explanation: The track key helps Angular identify unique items in a list, optimizing rendering performance by only re-rendering elements that have actually changed, rather than the entire list.

Examples:

<!-- Good: Primitive values -->
@for (name of names; track name) {
  <li>{{ name }}</li>
}

<!-- Good: Objects with a unique ID -->
@for (user of users; track user.id) {
  <li>{{ user.name }}</li>
}

<!-- Bad: Using the object directly for tracking -->
@for (user of users; track user) {
  <li>{{ user.name }}</li>
}

2.3 Prefer inject Function for Dependency Injection

Rule: Prefer using the inject function over constructor parameter injection for dependencies.

Explanation: The inject function provides a more flexible and tree-shakeable way to inject dependencies, especially outside of constructors (e.g., in field initializers or functions).

Examples:

// Good
import { inject } from '@angular/core';
import { MyService } from './my.service';

@Component({...})
export class MyComponent {
  readonly #myService = inject(MyService);

  // ...
}

// Bad (less preferred)
import { MyService } from './my.service';

@Component({...})
export class MyComponent {
  constructor(private myService: MyService) {
    // ...
  }
}

2.4 Use Standalone Components, Directives, and Pipes

Rule: All new components, pipes, and directives should be standalone.

Explanation: Standalone components are the new default in latest versions, and they simplify the Angular module system, reduce boilerplate, and improve tree-shaking, leading to smaller bundle sizes and easier development.

Example:

// Good: Standalone component
import { Component } from '@angular/core';

@Component({
  standalone: true,
  selector: 'app-my-standalone',
  template: `<p>This is a standalone component.</p>`,
})
export class MyStandaloneComponent {}

2.5 Use [class] and [style] Bindings

Rule: Do not use [ngClass] and [ngStyle]. Instead, use the more performant and direct [class] and [style] attribute bindings.

Explanation: The [class] and [style] bindings offer better performance and are often more straightforward for dynamic class and style manipulation.

Examples:

<!-- Good: [class] for single class -->
<div [class.active]="isActive"></div>

<!-- Good: [class] for multiple classes (object syntax) -->
<div [class]="{'active': isActive, 'highlight': isHighlight}"></div>

<!-- Good: [style] for single style property -->
<div [style.color]="textColor"></div>

<!-- Good: [style] for multiple style properties (object syntax) -->
<div [style]="{'background-color': bgColor, 'padding': '10px'}"></div>

<!-- Bad: [ngClass] -->
<div [ngClass]="{'active': isActive}"></div>

<!-- Bad: [ngStyle] -->
<div [ngStyle]="{'color': textColor}"></div>

3. Component Design & Structure

3.1 Container and Presentational Components

Rule: Components should be designed using the container (smart) and presentational (dumb) component approach. Container components handle data retrieval and logic, while presentational components focus solely on displaying data and emitting UI events.

Explanation: This separation of concerns improves reusability, testability, and maintainability.

Examples:

Container Component (UserPageContainerComponent): Fetches user data from a service, handles loading states, and passes data to a presentational component.
Presentational Component (UserDetailComponent): Receives user data via input(), displays it, and emits events (e.g., (editUser)) when UI interactions occur.

3.2 Multiple Container Components Per Page

Rule: A page can have multiple container components to avoid a single large container component managing data for many presentational components.

Explanation: This prevents monolithic container components, promoting smaller, more focused containers that manage specific sections of a page's data and logic.

3.3 Components Focused on Presentation

Rule: Keep components and directives focused on presentation. The code within them should primarily relate to the UI shown on the page. Logic decoupled from the UI (e.g., complex form validation, data transformations, business logic) should reside in separate files (e.g., services, utility functions).

Explanation: This ensures components remain lean and focused on their primary responsibility: rendering the UI. It improves reusability of business logic and makes components easier to test.

3.4 Inline Templates, Separate Styles

Rule: Components should use inline templates (template: '...'), but keep styles in a separate file (styleUrls: [...]).

Explanation: Inline templates make it easier to view the component's structure alongside its logic. Separating styles into dedicated files allows for better organization, reusability, and tooling support for CSS.

Example:

// Good
@Component({
  selector: 'app-my',
  standalone: true,
  template: `
    <div class="wrapper">
      <h1>{{ title }}</h1>
      <button (click)="sayHello()">Click Me</button>
    </div>
  `,
  styleUrls: ['./my.component.scss'] // Separate style file
})
export class MyComponent {
  protected readonly title = 'Hello';

  protected sayHello(): void { /* ... */ }
}

3.5 Template Property Order

Rule: In templates, element properties should be ordered as follows:

Any id property
Normal HTML attributes (e.g., src, alt, type, placeholder)
Property bindings ([property])
Event bindings ((event))
Two-way data bindings ([(ngModel)] or "banana in a box" properties)

Explanation: This consistent ordering improves template readability and makes it easier to scan for different types of bindings.

Example:

<!-- Good -->
<input
  id="username-input"
  type="text"
  placeholder="Enter username"
  [value]="userName()"
  (input)="logInput($event)"
  [(ngModel)]="userModel"
>

4. State Management & Reactivity

4.1 Prefer Signals or Pipes for Data Transformation

Rule: Only call functions from the template to handle events. If you need to transform data to be displayed or bound, always use signals (specifically computed signals) or pipes.

Explanation: Calling functions directly from the template for data transformation can lead to performance issues due to repeated execution during change detection. Signals and pipes are optimized for reactive data transformations.

Examples:

// Good: Using a computed signal for transformation
export class MyComponent {
  protected readonly firstName = signal('John');
  protected readonly lastName = signal('Doe');
  protected readonly fullName = computed(() => `${this.firstName()} ${this.lastName()}`);
}
// Template: {{ fullName() }}

// Good: Using a pipe for transformation
// my-uppercase.pipe.ts
@Pipe({ name: 'myUppercase', standalone: true })
export class MyUppercasePipe implements PipeTransform {
  transform(value: string): string {
    return value.toUpperCase();
  }
}
// Template: {{ myText | myUppercase }}

// Bad: Calling a function for transformation in template
export class MyComponent {
  protected readonly text = 'hello';

  getUppercaseText(): string {
    return this.text.toUpperCase();
  }
}
// Template: {{ getUppercaseText() }} // Avoid this

4.2 Avoid Manual Subscriptions (Prefer toSignal or async pipe)

Rule: Try to avoid manual subscriptions to RxJS Observables. Prefer using the toSignal utility function to convert Observables into signals, or use the async pipe directly in the template.

Explanation: toSignal and the async pipe automatically manage subscriptions and unsubscriptions, preventing memory leaks and simplifying reactive code.

Examples:

// Good: Using toSignal
import { toSignal } from '@angular/core/rxjs-interop';
import { MyService } from './my.service';

@Component({...})
export class MyComponent {
  readonly #myService = inject(MyService);
  protected readonly data = toSignal(this.#myService.getData(), { initialValue: [] });
}
// Template: @for (item of data(); track item.id) { ... }

// Good: Using async pipe
import { Observable } from 'rxjs';
import { MyService } from './my.service';

@Component({...})
export class MyComponent {
  readonly #myService = inject(MyService);
  protected readonly data$ = this.#myService.getData();
}
// Template: @if (data$ | async; as data) { @for (item of data; track item.id) { ... } }

// Bad: Manual subscription (among other things)
import { MyService } from './my.service';
import { Subscription } from 'rxjs';

@Component({...})
export class MyComponent implements OnInit, OnDestroy {
  private myService = inject(MyService);
  private subscription: Subscription;
  data: any[] = [];

  ngOnInit() {
    this.subscription = this.myService.getData().subscribe(data => this.data = data);
  }

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

4.3 Manual Subscription Cleanup with takeUntilDestroyed

Rule: If you absolutely need to subscribe to a stream manually, ensure you close the subscription using takeUntilDestroyed and by injecting DestroyRef.

Explanation: takeUntilDestroyed is a powerful RxJS operator introduced in Angular that automatically unsubscribes from an observable when the injection context it's used within (such as a component, directive, service, or pipe) is destroyed. This effectively prevents memory leaks by ensuring that subscriptions are cleaned up without needing manual ngOnDestroy logic for each subscription.

Example:

// Good: Manual subscription with takeUntilDestroyed
import { Component, inject, DestroyRef } from '@angular/core';
import { MyService } from './my.service';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';

@Component({...})
export class MyComponent {
  readonly #myService = inject(MyService);
  readonly #destroyRef = inject(DestroyRef);
  protected data: unknown[] = [];

  constructor() {
    this.#myService.getData()
      .pipe(takeUntilDestroyed(this.#destroyRef))
      .subscribe(data => {
        this.data = data;
        console.log('Received data:', data);
      });
  }
}

4.4 Avoid effect When computed is Sufficient

Rule: Avoid using effect whenever possible. Prefer using computed properties if you need to propagate state changes.

Explanation: computed signals are pure and memoized, making them ideal for deriving new reactive values from existing ones. effect should be reserved for side effects that do not produce new reactive values. Overusing effect can lead to complex and hard-to-debug reactive graphs.

Examples:

// Good: Using computed for derived state
export class MyComponent {
  protected readonly quantity = signal(1);
  protected readonly price = signal(10);
  protected readonly total = computed(() => this.quantity() * this.price()); // total is derived reactive state
}

// Good: Appropriate use of effect (side effect)
export class MyComponent {
  protected readonly #count = signal(0);

  constructor() {
    effect(() => {
      console.log(`Current count is: ${this.count()}`); // Logging is a side effect
    });
  }
}

// Bad: Using effect to derive state that could be a computed
export class MyComponent {
  protected readonly firstName = signal('John');
  protected readonly lastName = signal('Doe');
  protected readonly fullName = signal(''); // Imperative state

  constructor() {
    effect(() => {
      this.fullName.set(`${this.firstName()} ${this.lastName()}`); // Avoid this, use computed
    });
  }
}

4.5 Appropriate Use of effect

Rule: effect should be used only when you need to rely on a reactive value and the other end isn't reactive. This includes scenarios like:

Logging data.
Keeping data in sync with storage (e.g., localStorage).
Adding custom DOM behavior that cannot be expressed with template syntax.
Performing custom rendering to a , charting library, or other third-party UI library.

Explanation: effect is designed for side effects that occur in response to reactive value changes. It's not for deriving new reactive state.

Example:

// Good: Syncing state with localStorage
export class MyComponent {
  protected readonly settings = signal({ theme: 'light' });

  constructor() {
    effect(() => {
      localStorage.setItem('appSettings', JSON.stringify(this.settings()));
    });
  }
}

4.6 Use untracked in effect for Non-Reactive Signal Access

Rule: Use untracked within an effect whenever you need to access a signal's value but do not want that signal to become a dependency of the effect.

Explanation: By default, any signal accessed within an effect becomes a dependency, causing the effect to re-execute whenever that signal changes. untracked allows you to read a signal's value without creating this dependency, preventing unnecessary re-executions of the effect when only the untracked signal changes. This is useful when a signal's value is needed for a side effect, but the side effect itself doesn't need to react to changes in that specific signal.

Examples:

// Good: Using untracked to prevent unnecessary effect re-execution
import { effect, signal, untracked } from '@angular/core';

export class MyComponent {
  protected readonly mainData = signal('Important Data');
  protected readonly loggingPreference = signal(true); // This signal should not re-trigger the effect

  constructor() {
    effect(() => {
      // This effect reacts to changes in `mainData`
      const data = this.mainData();

      // Access `loggingPreference` without making it a dependency
      if (untracked(this.loggingPreference)) {
        console.log(`Effect re-executed. Data: ${data}`);
      } else {
        console.log(`Effect re-executed. Logging disabled.`);
      }
    });
  }
}

// Bad: Effect re-executes when `loggingPreference` changes, which might be unnecessary
export class MyComponent {
  protected readonly mainData = signal('Important Data');
  protected readonly loggingPreference = signal(true);

  constructor() {
    effect(() => {
      const data = this.mainData();
      // This effect will re-execute if `loggingPreference` changes, even if `mainData` is the primary trigger
      if (this.loggingPreference()) {
        console.log(`Effect re-executed. Data: ${data}`);
      } else {
        console.log(`Effect re-executed. Logging disabled.`);
      }
    });
  }
}

4.7 State Services for Shared Data

Rule: Use state services to share certain state across components, especially to avoid prop-drilling. These services should use a BehaviorSubject or signal to store the state. The state should be immutable and readonly, with updates only possible via methods within the service itself.

Explanation: State services provide a centralized and controlled way to manage application state, making it easier to reason about data flow and prevent unintended mutations.

Examples:

// Good: user-state.service.ts
import { Injectable, signal, computed } from '@angular/core';
import { User } from './user.model';

@Injectable({ providedIn: 'root' })
export class UserStateService {
  readonly #currentUser = signal<User | null>(null);

  readonly currentUser = this.#currentUser.asReadonly();
  readonly isLoggedIn = computed(() => this.#currentUser() !== null);

  login(user: User): void {
    // Perform login logic, then update state
    this.#currentUser.set(user);
  }

  logout(): void {
    this.#currentUser.set(null);
  }
}

// Good: Component consuming the state service
import { Component, inject } from '@angular/core';
import { UserStateService } from './user-state.service';

@Component({...})
export class UserProfileComponent {
  readonly #userStateService = inject(UserStateService);
  protected readonly currentUser = this.#userStateService.currentUser; // Access readonly signal
  protected readonly isLoggedIn = this.#userStateService.isLoggedIn;

  logout(): void {
    this.#userStateService.logout();
  }
}

4.8 Avoid Prop-Drilling

Rule: For direct component communication, use input() and output(). However, if data needs to be passed through multiple layers of components (prop-drilling), prefer creating a state service to share the data.

Explanation: Prop-drilling makes components tightly coupled and difficult to refactor. State services provide a more scalable solution for sharing data across distant components.

5. Change Detection

5.1 Always Use OnPush Change Detection

Rule: Always use OnPush change detection for components.

Explanation: OnPush change detection significantly improves performance by only checking components for changes when their inputs change, an event is emitted, or an observable they subscribe to emits a new value. This is crucial for large applications.

Example:

// Good
import { Component, ChangeDetectionStrategy } from '@angular/core';

@Component({
  selector: 'app-my-component',
  standalone: true,
  template: `...`,
  changeDetection: ChangeDetectionStrategy.OnPush // Always use OnPush
})
export class MyComponent {}

6. Lifecycle Hooks

6.1 Avoid Lifecycle Hooks Where Possible

Rule: Try to avoid using traditional lifecycle hooks. Properties should be initialized alongside their declaration.

ngOnInit: Mostly replaceable with constructor logic or effect.
ngOnChanges: Replaceable with computed signals or effects reacting to input changes.
ngAfterViewInit: Replaceable with effect or viewChild.
ngAfterContentInit: Replaceable with effect or contentChild.
ngAfterContentChecked and ngAfterViewChecked: Replaceable with afterRenderEffect or afterNextRenderEffect.
ngOnDestroy: Replaceable by injecting DestroyRef and using takeUntilDestroyed for subscriptions, or DestroyRef.onDestroy(() => ...) for other cleanup.

Explanation: Modern Angular features (signals, inject, takeUntilDestroyed, afterRenderEffect) provide more granular and often more performant ways to manage component lifecycle concerns, reducing the need for traditional hooks.

6.2 Keep Lifecycle Hooks Simple (If Used)

Rule: If you absolutely need to use a lifecycle hook, make sure to keep them simple. Move complex logic to dedicated methods and just call them from the hook instead of placing all the logic directly inside the hook.

Explanation: This improves readability and testability of the logic within the hook.

Example:

// Good: Simple ngOnInit
export class MyComponent implements OnInit {
  ngOnInit(): void {
    this.loadData(); // Call a dedicated method
  }

  private loadData(): void {
    // Complex data loading logic here
  }
}

// Bad: Complex ngOnInit
export class MyComponent implements OnInit {
  ngOnInit(): void {
    // All complex data loading logic directly here
    // ... many lines of code ...
  }
}

7. Naming Conventions

7.1 Event Handler Naming

Rule: Name event handlers for what they do, not for the triggering event. Avoid generic names like handleClick or onButtonClick.

Explanation: Descriptive names make the code's intent clearer and improve maintainability.

Examples:

// Good
saveUser() { /* ... */ }
toggleSidebar() { /* ... */ }
submitForm() { /* ... */ }

// Bad
handleClick() { /* ... */ }
onButtonClick() { /* ... */ }

8. Internationalization (i18n)

8.1 "Key as a Value" for Translations

Rule: New texts should be added to the translation files using the "key as a value" rule. If the text is "Hello world", it should be added to the translations as: "Hello world": "Hello world".

Explanation: This simplifies the initial translation process, as the default language uses the text itself as the key, making it immediately readable. This also helps identify untranslated strings easily, and using libraries to extract translations from our code.

Example:

// en.json
{
  "Hello world": "Hello world",
  "Welcome to our app": "Welcome to our app"
}

9. Code Organization

9.1 Access Modifiers

Rule: Use access modifiers as follows:

protected (by default): For properties or methods used inside the component class and its template.
private: For properties or methods used only inside the component class. For properties, prefer JavaScript private fields (#propertyName) over the private keyword.
public (no keyword): For properties or methods used outside the component (e.g., input(), output(), or methods called from other components). Do not add the public keyword, as properties and methods are public by default.

Explanation: This provides clear visibility boundaries for class members, improving encapsulation and making it easier to understand how components interact. Using JS private fields (#) offers true encapsulation at the language level.

Examples:

export class MyComponent {
  // Public property (no keyword needed) - e.g., an input()
  readonly data = input<Data>();

  // Protected property - accessible in template and class
  protected readonly isLoading = signal(false);

  // Private property - accessible only within the class, using JS private field
  readonly #counterService = inject(CounterService);

  // Protected method - accessible in template and class
  protected incrementCounter(): void {
    this.incrementLocalCounter();
  }

  // Private method - accessible only within the class
  private incrementLocalCounter(): void {
    this.#counterService.incrementCounter();
    console.log('Internal counter:', this.#counterService.count());
  }
}

9.2 Import Order

Rule: Imports should be sorted in this order:

External libraries (e.g., @angular/*, rxjs, lodash)
Internal libraries (e.g., @app/shared, @app/core)
Internal relative imports (e.g., ./my-service, ../models)

Explanation: Consistent import ordering makes files easier to read and navigate, and helps prevent merge conflicts.

Example:

// Good
import { Component, OnInit, inject, DestroyRef } from '@angular/core';
import { CommonModule } from '@angular/common';
import { Observable } from 'rxjs';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';

import { SharedModule } from '@app/shared'; // Internal library
import { AuthService } from '@app/core/auth'; // Internal library

import { UserService } from './user.service'; // Relative import
import { User } from '../models/user.model'; // Relative import

A Note on These Guidelines

These guidelines are a distillation of personal experience working on large Angular projects, combined with insights from the official Angular Style Guide and various articles on best practices.

Please be aware that these rules may contain errors and some are heavily opinionated. Your feedback is highly valued! Feel free to leave comments with corrections, suggestions, or to add other rules that you believe would be beneficial.

If you found this article helpful, please consider sharing it with your colleagues and network!

Angular + Gemini Pro Vision

Mauricio Arce Torrez — Thu, 16 May 2024 02:15:51 +0000

Esta es la segunda parte de una serie de artículos sobre Angular + Gemini

Primera parte: Angular + Gemini Pro
Segunda parte: Angular + Gemini Pro Vision

Integrando Angular y Gemini Pro Vision

Bienvenido a la segunda parte de este tutorial en el que daremos una introducción a cómo integrar Angular y Gemini Vision Pro de una forma muy sencilla.

Empezando:

1. Actualizar nuestro gemini.service para que reciba archivos

Para poder enviar imágenes a nuestro modelo de Gemini, necesitamos actualizar nuestro servicio con una nueva función que reciba un archivo. Para ello agregaremos una nueva función llamada sendImage que reciba un archivo y devuelva una promesa con el resultado.:

async sendImage(file: File): Promise<string> {
}

Debemos usar un nuevo modelo, el gemini-pro-vision, el cual es un modelo que nos permitirá enviar imágenes. Para ello, moveremos la instancia de nuestro modelo dentro de cada función:

async sendPrompt(prompt: string): Promise<string> {
  const model = this.#genAI.getGenerativeModel({ model: 'gemini-pro' });

  try {
    const { response } = await model.generateContent(prompt);
    return response.text();
  } catch (error) {
    console.error(error);
    return 'An error has occurred. Please try again.';
  }
}

async sendImage(file: File): Promise<string> {
  const model = this.#genAI.getGenerativeModel({
    model: 'gemini-pro-vision',
  });
}

El modelo recibe un dato de tipo Part, así que debemos convertir nuestro archio a este tipo de dato:

async sendImage(file: File): Promise<string> {
  const model = this.#genAI.getGenerativeModel({
    model: 'gemini-pro-vision',
  });
  const part = await this.convertFileToGenerativePart(file);
}

async convertFileToGenerativePart(file: File): Promise<Part> {
  const base64EncodedDataPromise = new Promise<string>((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve((reader.result as string).split(',')[1]);
    reader.readAsDataURL(file);
  });

  return {
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

Para concluir, debemos enviar la imagen junto a un prompt al modelo, y asegurarnos de manejar cualquier error que pueda surgir:

async sendImage(file: File): Promise<string> {
  const model = this.#genAI.getGenerativeModel({
    model: 'gemini-pro-vision',
  });

  try {
    const part = await this.convertFileToGenerativePart(file);
    const prompt = '¿Qué es lo que ves en esta imagen?';
    const { response } = await model.generateContent([prompt, part]);

    return response.text();
  } catch (error) {
    console.error(error);
    return 'An error has occurred. Please try again.';
  }
}

Nuestro servicio debería lucir así:

import { Injectable } from '@angular/core';
import { GoogleGenerativeAI, Part } from '@google/generative-ai';

@Injectable({
  providedIn: 'root',
})
export class GeminiService {
  readonly #API_KEY = '<YOUR-API-KEY>';
  readonly #genAI = new GoogleGenerativeAI(this.#API_KEY);

  async sendPrompt(prompt: string): Promise<string> {
    const model = this.#genAI.getGenerativeModel({ model: 'gemini-pro' });

    try {
      const { response } = await model.generateContent(prompt);
      return response.text();
    } catch (error) {
      console.error(error);
      return 'An error has occurred. Please try again.';
    }
  }

  async sendImage(file: File): Promise<string> {
    const model = this.#genAI.getGenerativeModel({
      model: 'gemini-pro-vision',
    });

    try {
      const part = await this.convertFileToGenerativePart(file);
      const prompt = '¿Qué es lo que ves en esta imagen?';
      const { response } = await model.generateContent([prompt, part]);

      return response.text();
    } catch (error) {
      console.error(error);
      return 'An error has occurred. Please try again.';
    }
  }

  async convertFileToGenerativePart(file: File): Promise<Part> {
    const base64EncodedDataPromise = new Promise<string>((resolve) => {
      const reader = new FileReader();
      reader.onloadend = () => resolve((reader.result as string).split(',')[1]);
      reader.readAsDataURL(file);
    });

    return {
      inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
    };
  }
}

2. Enviar la imagen al modelo

Agregaremos un nuevo input en nuestro chat.component.html para que el usuario pueda enviar una imagen:

<input
  #fileInput
  type="file"
  accept="image/*"
  (change)="sendImageMessage(fileInput.files)"
/>

Podemos ver que cada que se selecciona un archivo, se llama a la función sendImageMessage con el archivo seleccionado, la cual debemos implementar en nuestro chat.component.ts:

sendImageMessage(files: FileList | null): void {
  if (!files) {
    return;
  }

  const file = files[0];

  this.#geminiService
    .sendImage(file)
    .then((response) => this.response.set(response));
}

Nuestra función valida si se seleccionó un archivo, y si es así, llama a nuestro servicio para enviar la imagen y mostrar la respuesta en nuestro chat.

3. Mostrar la imagen

Ya por último, debemos mostrar la imagen en nuestro chat.component.html:

<img *ngIf="imageSrc()" [src]="imageSrc()" />

Estamos asumiendo que existe un signal imageSrc que contiene la URL de la imagen. Para ello, debemos agregarlo a nuestro chat.component.ts:

imageSrc = signal('');

Y actualizar nuestra función sendImageMessage para que guarde la URL de la imagen en nuestro signal:

sendImageMessage(files: FileList | null): void {
  if (!files) {
    return;
  }

  const file = files[0];
  this.imageSrc.set(URL.createObjectURL(file));

  this.#geminiService
    .sendImage(file)
    .then((response) => this.response.set(response));
}

Con estos cambios, ya deberíamos poder enviar imágenes a nuestro modelo de Gemini y mostrar la respuesta en nuestro chat.

¡Y eso es todo! Espero que este tutorial te haya sido de ayuda. Si tienes alguna duda, no dudes en contactarme.

Angular + Gemini Pro

Mauricio Arce Torrez — Fri, 03 May 2024 14:16:25 +0000

Esta es la segunda parte de una serie de artículos sobre Angular + Gemini

Primera parte: Angular + Gemini Pro
Segunda parte: Angular + Gemini Pro Vision

Integrando Angular y Gemini

Bienvenido a este tutorial en el que daremos una introducción a cómo integrar Angular y Gemini de una forma muy sencilla.

Requisitos previos:

Tener Node.js instalado en tu sistema. Puedes descargarlo desde https://nodejs.org/en/download.
Tener instalado @angular/cli. Puedes instalarlo usando npm con este comando: npm install --global @angular/cli.
Familiaridad básica con HTML, CSS y JavaScript.
Familiaridad básica con Angular.

Empezando:

1. Creación del proyecto en Angular

Abre una terminal y navega hasta la ubicación donde deseas crear el proyecto, una vez ahí corre el siguiente comando:

ng new gemini-poc

Remplaza "gemini-poc" con el nombre que prefieras para tu proyecto. La CLI te guiará en el proceso de creación.

2. Instalar librería de Google Generative AI

Para poder usar un modelo de Gemini desde nuestra aplicación, debemos instalar la dependencia @google/generative-ai. Para ello corremos el comando:

npm install @google/generative-ai

3. Implementar servicio que se conectará con Gemini

Crea un servicio para separar la lógica de conexión con el modelo. Para ello corre el comando:

ng generate service gemini

"gemini" es el nombre que le estamos dando a nuestro servicio, puedes darle otro nombre si lo deseas.

Necesitamos una instancia del modelo para poder mandarle prompts:

readonly #API_KEY = '<YOUR-API-KEY>';
readonly #genAI = new GoogleGenerativeAI(this.#API_KEY);
readonly #model = this.#genAI.getGenerativeModel({ model: 'gemini-pro' });

La API key veremos cómo obtenerla en el siguiente paso.
#genAI es una propiedad privada que contiene una instancia de la librería.
#model es una instancia del modelo, el mismo está usando gemini-pro, el cual es el modelo para entradas de solo texto. Puedes ver las diferentes variaciones de modelos aquí.

También debemos implementar una función que se encargue de enviar prompts a nuestro modelo para generar contenido:

async sendPrompt(prompt: string): Promise<string> {
  try {
    const { response } = await this.#model.generateContent(prompt);
    return response.text();
  } catch (error) {
    console.error(error);
    return 'An error has occurred. Please try again.';
  }
}

Nuestro servicio debería lucir así:

import { Injectable } from '@angular/core';
import { GoogleGenerativeAI } from '@google/generative-ai';

@Injectable({
  providedIn: 'root',
})
export class GeminiService {
  readonly #API_KEY = '<YOUR-API-KEY>';
  readonly #genAI = new GoogleGenerativeAI(this.#API_KEY);
  readonly #model = this.#genAI.getGenerativeModel({ model: 'gemini-pro' });

async sendPrompt(prompt: string): Promise<string> {
  try {
    const { response } = await this.#model.generateContent(prompt);
    return response.text();
  } catch (error) {
    console.error(error);
    return 'An error has occurred. Please try again.';
  }
}
}

4. Obtener nuestra API key

Accede a Google AI Studio y crea una nueva API key. Asegúrate de guardar este valor una vez se haya generado y no compartirlo con nadie. No olvides que en caso de perderlo o compartirlo por accidente, siempre puedes eliminar la key y crear una nueva.

Reemplaza la key que obtuviste en la propiedad del servicio creado en el anterior paso. Toma en cuenta que el código con tu key no debería ser publicado, solo lo estamos agregando de forma directa en el código para desarrollo local.

5. Actualiza el app.component

Debemos actualizar el template y el componente app.component para poder mandar los prompts.

La lógica del componente necesita propiedades para almacenar la respuesta de Gemini y una función que utilice el servicio para poder mandar el prompt.

Para guardar la respuesta podemos hacer uso de un signal:

response = signal('');

Mientras que nuestra función podría lucir así:

readonly #geminiService = inject(GeminiService);

sendPrompt(prompt: string): void {
  this.#geminiService
    .sendPrompt(prompt)
    .then((response) => this.response.set(response));
}

Ahora, necesitamos renderizar la repuesta de Gemini en nuestro template (app.component.html):

<p>
  {{ response() }}
</p>

También debemos agregar un campo de texto que llame a nuestra función sendPrompt cada que presionemos la tecla "Enter":

<input
  #promptInput
  placeholder="Introduce una petición aquí"
  type="text"
  (keyup.enter)="sendPrompt(promptInput.value)"
/>

Después de estos cambios, nuestro archivo app.component.ts debería lucir así:

import {
  ChangeDetectionStrategy,
  Component,
  inject,
  signal,
} from '@angular/core';

import { GeminiService } from '../core/services/gemini.service';

@Component({
  selector: 'app-chat',
  standalone: true,
  imports: [],
  templateUrl: './chat.component.html',
  styleUrl: './chat.component.css',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export default class ChatComponent {
  response = signal('');
  readonly #geminiService = inject(GeminiService);

  sendPrompt(prompt: string): void {
    this.#geminiService
      .sendPrompt(prompt)
      .then((response) => this.response.set(response));
  }
}

Y el archivo app.component.html así:

<p>
  {{ response() }}
</p>

<input
  #promptInput
  placeholder="Introduce una petición aquí"
  type="text"
  (keyup.enter)="sendPrompt(promptInput.value)"
/>

6. A probar nuestra app

Si hasta aquí hemos hecho todo bien, deberíamos poder correr nuestra app con el comando ng serve e interactuar con la misma abriendo en nuestro navegador web http://localhost:4200:

Angular Micro-frontends

Mauricio Arce Torrez — Tue, 11 Jul 2023 23:40:09 +0000

Micro-frontends es la introducción de un concepto como el de micro-servicios pero aplicados al desarrollo del lado del cliente. Nos permite tener varios proyectos del lado del frontend conectados entre sí para crear una sola aplicación más grande.

¿Por qué usar Micro-frontends?

Puedes desacoplar el proyecto en distintas bases de código.
Es más sencillo entender, extender y mantener el código al manejar proyectos más pequeños.
Las dependencias pueden ser actualizadas de forma independiente (siempre y cuando no sean dependencias compartidas).
Los builds son desacoplados y escalables.
Los artifacts pueden ser publicados de forma independiente con un impacto mínimo a otros proyectos.
El riesgo de cada publicación se reduce.
Se pueden tener equipos independientes y especializados en cada proyecto.
Cada equipo puede trabajar con una tecnología distinta (no es lo recomendado, pero de poder se puede).

Casos de uso

Migrar/actualizar bases de código gradualmente. Por ejemplo, para un proyecto hecho en AngularJS puedes empezar a trabajar en nuevos features usando la última versión de Angular, a medida que se actualiza el código legacy a Angular también.
Compartir un feature en diferentes aplicaciones. Un solo micro-frontend puede ser utilizado en múltiples proyectos.
Equipos autónomos trabajan en diferentes features del proyecto, cada uno en un micro-frontend distinto.
Deployments (publicaciones) independientes. Puedes trabajar en un cambio que afecta un micro-frontend específico y publicarlo sin necesidad de hacer deploy de todo el proyecto.

Consideraciones al implementar micro-frontends

Evita en lo posible mezclar frameworks/librerías en diferentes micro-frontends al menos que sea estrictamente necesario. El mezclar tecnologías genera bundles más grandes al no permitir el compartir dependencias, además de mezclar conceptos y guidelines al momento del desarrollo.
Procura manejar dependencias compartidas y crear librerías para el código común, así el mismo puede ser reutilizado. Sin embargo, ten cuidado de no acoplar demasiado el código, esto disminuye la autonomía de los equipos trabajando en cada proyecto.

¿Cómo implementar micro-frontends?

iframe
Web Components (custom elements)
Single-spa
Module Federation

En este artículo nos concentraremos en esta última opción, Module Federation.

Module Federation

Module Federation es un feature de Webpack, un module bundler muy popular para JavaScript, además de ser la herramienta que usa Angular para este propósito. Con Module Federation podemos habilitar la carga dinámica de módulos de múltiples sistemas independientes, los cual nos habilita para la creación de aplicaciones que siguen una estructura basada en micro-frontends.

Usando Module Federation en Angular

Para poder utilizar Module Federation en Angular, tenemos disponible la siguiente herramienta: @angular-architects/module-federation.

Para ejemplificar su uso, implementaremos tres proyectos, uno que servirá como host o contenedor de la aplicación, un micro-frontend que vendría a llenar el contenido de la aplicación, y una librería con la cual podremos compartir información entre ambas aplicaciones.

Creando el host

Usando el CLI de Angular, ejecutamos el siguiente comando para crear nuestro host:

ng new host --routing

Hay que notar que le pasamos la opción --routing para que se nos cree un módulo separado que se encargará de definir la configuración de rutas, mediante la cual luego podremos cargar el módulo remoto que crearemos en el otro proyecto.

Lo siguiente que haremos será ingresar al proyecto y en la raíz correr el schematic necesario para agregar el plugin de Module Federation:

ng add @angular-architects/module-federation --type host

Cuando se nos pregunte por el nombre y puerto del proyecto, le daremos el nombre host y el puerto 4200. El valor del nombre es el de nuestro proyecto Angular, para el puerto podemos definir el que queramos, mantendremos 4200 para este ejemplo.

Debes notar que al correr el schematic le pasamos una opción --type host. Existen 3 posibles valores para esta opción type:

host
dynamic-host
remote

El usar la adecuada nos proporcionará una configuración más acorde al tipo de proyecto, siendo host y dynamic-host las opciones usadas para crear un proyecto contenedor, el que se encarga de cargar los proyectos remotos (remote), la única diferencia entre ambas es que al usar dynamic-host también se creará un archivo donde podremos definir los paths de los diferentes micro-frontends que vayamos a usar.

Al correr el schematic notaremos cambios en algunos archivos, como ser configuración adicional en el angular.json file para usar un builder distinto, además de que se agregará una propiedad extraWebpackConfig que apuntará a la ruta de un archivo recién creado, el webpack.config.js. En este último archivo tendremos la configuración base necesaria con la ruta de los micro-frontends que vayamos a consumir (remotes) y las dependencias compartidas (shared).

Creando el micro-frontend

Igual haremos uso del CLI para crear el proyecto, tomando en cuenta el hacerlo en un path distinto al del host:

ng new mfe

Esta vez no es necesario definir un módulo de rutas, ya que este proyecto solo tendrá feature modules que serán cargados desde el proyecto host.

Ingresamos al proyecto y corremos el schematic para agregar Module Federation, teniendo cuidado de usar el type remote:

ng add @angular-architects/module-federation --type remote

El nombre del proyecto es mfe y para el puerto debemos usar uno distinto al del proyecto host, en mi caso usaré el 3000 para que haga match con la configuración por defecto que ya se encuentra en el archivo webpack.config.js en la sección de remotes del proyecto host.

Al correr el schematic notaremos cambios muy similares a los que ocurrieron en el proyecto host, pero veremos algunas diferencias en el webpack.config.js generado, ya que en vez de tener una propiedad remotes tendrá una propiedad llamada exposes. Modificaremos esta propiedad más adelante para que concuerde con el módulo que crearemos y de esta forma poder exponerlo para que sea consumido por el host.

Lo siguiente será crear nuestro feature module, para ello creamos un par de nuevos módulos, el del feature como tal y el de rutas para el mismo:

ng g m feature-one --routing

Y también creamos un componente principal para este módulo:

ng g c feature-one

Nos aseguraremos de tener bien configurado nuestro módulo de rutas recién creado (feature-one-routing.module.ts). Para ello, definimos que para el path vacío se cargue el componente recién creado:

import { FeatureOneComponent } from './feature-one.component';

const routes: Routes = [
  {
    path: '',
    component: FeatureOneComponent,
  },
];

Ahora, a diferencia de un feature module normal cargado por lazy loading, este lo debemos importar en el módulo raíz (app.module.ts) para que sea parte de la compilación de TypeScript:

import { FeatureOneModule } from './feature-one/feature-one.module';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, FeatureOneModule],
  bootstrap: [AppComponent],
})
export class AppModule {}

Ahora sí, volvemos al webpack.config.js y realizamos la modificación que teníamos pendiente en la propiedad exposes:

  exposes: {
    './FeatureOneModule': './src/app/feature-one/feature-one.module.ts',
  },

Debemos prestar atención al nombre de la propiedad que estamos agregando, en este caso ./FeatureOneModule, ya que será el valor que utilizaremos en el proyecto host al cargar este módulo.

Ya estamos casi listos para conectar nuestros dos proyectos.

Conectando ambos proyectos

Ve al módulo de rutas del módulo raíz del proyecto host (app-routing.module.ts) y define que para la ruta vacía se haga una redirección a la ruta feature-one. Para esta última ruta usaremos lazy loading para cargar el feature module que creamos en nuestro proyecto mfe, pero notarás que en vez de importarlo localmente, como se haría usualmente para un módulo dentro del mismo proyecto, lo cargaremos de forma remota:

import { loadRemoteModule } from '@angular-architects/module-federation';

const routes: Routes = [
  {
    path: '',
    redirectTo: 'feature-one',
    pathMatch: 'full',
  },
  {
    path: 'feature-one',
    loadChildren: () =>
      loadRemoteModule({
        type: 'module',
        remoteEntry: 'http://localhost:3000/remoteEntry.js',
        exposedModule: './FeatureOneModule',
      }).then((mod) => mod.FeatureOneModule),
  },
];

En type viene el tipo de elemento que estamos cargando, en este caso es un module.

En remoteEntry definimos la ruta del archivo remoto, es decir, del proyecto mfe. El nombre del archivo remoto por defecto lleva el nombre remoteEntry.js al momento de correr el schematic, sin embargo este es un nombre que podemos modificar si lo quisiéramos en la configuración del proyecto mfe más adelante. Para este tutorial lo dejaremos tal cual está.

En exposedModule nos debemos asegurar de poner el nombre que usamos en exposes de la configuración webpack del mfe.

Lo que resta por hacer es modificar nuestro template para que luzca como queremos. En este caso agregaremos una barra de navegación sin estilizarla demasiado para este ejemplo, además de tener en posición el elemento router-outlet, que será donde cargará el contenido de nuestras rutas. Reemplazamos el contenido de app.component.html por el siguiente:

<nav>
  <a routerLink="/feature-one"> Feature One </a>
  <!-- Aquí podemos seguir agregando más enlaces a otros feature modules, remotos o locales -->
</nav>

<main>
  <router-outlet></router-outlet>
</main>

¡Ya debería funcionar! Si corremos ambos proyectos (ng serve) y luego accedemos al path del host (http://localhost:4200), nuestra aplicación ya debería estar corriendo:

Aquí podemos ver ambos proyectos resaltados:

Muy bien, ahora solo falta tener un mecanismo para poder compartir datos a través de ambos proyectos.

Usando una librería para compartir información

Crearemos una librería para permitir el paso de datos e información entre ambos proyectos. Para ello, primero crearemos un workspace de angular vacío en un path distinto:

ng new libs --no-create-application

Accedemos al workspace y creamos la librería:

ng g library shared-library

En el path: projects/shared-library/src/lib/shared-library.service.ts encontraremos un servicio donde agregaremos un BehaviorSubject para ejemplificar cómo podemos compartir información:

import { BehaviorSubject } from 'rxjs';

@Injectable({
  providedIn: 'root',
})
export class SharedLibraryService {
  sharedData$ = new BehaviorSubject<string>('Hello World!');
}

Creamos un distribuible de nuestra librería corriendo el siguiente comando en la raíz de nuestro workspace:

npm run build

Notarás que se creó el distribuible en dist/shared-library. Accede a esa ruta y crea un symlink global de la librería usando este comando:

npm link

En el archivo package.json dentro de projects/shared-library podrás ver el nombre y la versión con la que se creó el symlink de la librería. Si no realizaste ningún cambio, los valores deberían ser shared-library y 0.0.1 respectivamente.

En cada uno de los proyectos anteriores debes instalar la librería que acabamos de crear creando un symbolic link del paquete global. Ve a la raíz de cada proyecto, detén la ejecución y corre el siguiente comando:

npm link shared-library

Una vez hecho esto, ve al webpack.config.js file de cada proyecto y modifica la propiedad shared para asegurarte de que se comparta una sola instancia de la librería en ambos proyectos:

  shared: {
    ...shareAll({
      singleton: true,
      strictVersion: true,
      requiredVersion: "auto",
    }),
    "shared-library": {
      singleton: true,
      strictVersion: true,
      requiredVersion: "0.0.1",
    },
  },

Debes definir que haya una sola instancia usando la propiedad singleton, además de asegurarte que ambos proyectos usen la misma versión de la librería con las propiedades strictVersion y requiredVersion.

Ahora nos iremos al proyecto host e inyectaremos el servicio de la librería compartida en el app.component.ts file para poder consumir la sharedData$:

import { SharedLibraryService } from 'shared-library';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
})
export class AppComponent {
  data$ = this.sharedService.sharedData$;

  constructor(private sharedService: SharedLibraryService) {}
}

Lo siguiente será hacer binding de data$ en el template (app.component.html):

<nav>
  <a routerLink="/feature-one"> Feature One </a>
  <!-- Aquí podemos seguir agregando más enlaces a otros feature modules, remotos o locales -->
</nav>

<main>
  <p>
    {{ data$ | async }}
  </p>
  <router-outlet></router-outlet>
</main>

Además, agregaremos un pequeño estilo para poder diferenciar este párrafo con la información compartida del que agregaremos en el proyecto mfe más adelante. En el archivo app.component.css colocamos lo siguiente:

p {
  color: blue;
}

Si corremos ambos proyectos, host y mfe, veremos lo siguiente:

¡Genial! El host ya consume la información compartida de la librería. Nos queda hacer algo muy parecido en el mfe.

Nos vamos al feature-one.component.ts del mfe y hacemos lo mismo, inyectamos el servicio compartido y nos creamos una propiedad pública para guardar la sharedData$ del servicio y mostrarla en el template. De forma adicional agregaremos una función que se encargará de actualizar la información compartida.

import { SharedLibraryService } from 'shared-library';

@Component({
  selector: 'app-feature-one',
  templateUrl: './feature-one.component.html',
  styleUrls: ['./feature-one.component.css'],
})
export class FeatureOneComponent {
  data$ = this.sharedService.sharedData$;

  constructor(private sharedService: SharedLibraryService) {}

  updateSharedData(): void {
    this.sharedService.sharedData$.next('Hello from the MFE');
  }
}

Nos queda actualizar el template (feature-one.component.html):

<p>
  {{ data$ | async }}
</p>

<button (click)="updateSharedData()">
  Update shared data
</button>

Y agregar un estilo (en feature-one.component.css) para diferenciar este párrafo del que tiene el host:

p {
  color: red;
}

Este será el resultado:

Ahora, solo nos queda asegurarnos de que efectivamente la información se está compartiendo. Para ello fue que agregamos la función que actualiza sharedData$ del servicio (updateSharedData). Si todo está correcto, al llamar a la función, la información compartida se debería actualizar tanto en el mfe como en el host:

¡Lo hicimos!

Apuntes finales

Esta es sola una introducción a cómo podemos empezar a implementar micro-frontends usando Angular. Espero de corazón te sea de mucha ayuda.

Puedes encontrar el código de todo lo que hicimos en este tutorial en el siguiente repositorio: https://github.com/combimauri/my-first-mfes

Mucha más información relacionada a Module Federation y la integración con Angular la verás aquí: https://www.angulararchitects.io/en/aktuelles/the-microfrontend-revolution-module-federation-in-webpack-5/

Si tienes consultas puedes hacerlas por aquí y/o dejármelas en mi GitHub, LinkedIn, Twitter o Threads.

Quiero hacer un agradecimiento especial a mis compañeros de trabajo: Allan Leon Mendieta, Sergio Lopez y Diego Garcia, quienes directa o indirectamente aportaron un montón a este artículo y en base a muchas partes de su investigación es que el mismo pudo ser completado.