DEV Community: Suguru Inatomi

Angular: Resource API Family System Diagram

Suguru Inatomi — Sun, 12 Jul 2026 00:57:00 +0000

In this article, I’ll provide an overview of the relationships within the Resource API family, which became stable in Angular v22.

Resource API Family

As of v22, the main public APIs included in the Resource API are as follows:

Resource<T> interface
WritableResource<T> interface
ResourceSnapshot<T> interface
resourceFromSnapshots function
resource function
httpResource function

Let’s confirm their positions within the API family while explaining each one.

`Resource<T>` Interface

This interface sits at the heart of the API family. The Resource API family can be broadly divided into APIs that represent Resource objects and factory APIs for creating Resource objects. The Resource<T> interface is the common base type for all Resource objects and serves as the return type for factory APIs.

export interface Resource<T> {
  readonly value: Signal<T>;
  readonly status: Signal<ResourceStatus>;
  readonly error: Signal<Error | undefined>;
  readonly isLoading: Signal<boolean>;
  readonly snapshot: Signal<ResourceSnapshot<T>>;

  hasValue(this: T extends undefined ? this : never): this is Resource<Exclude<T, undefined>>;
  hasValue(): boolean;
}

As you can see, Resource<T> is read-only, and its responsibility is to return the values and states held by the Resource as Signal types. If an object conforms to this interface, it can be considered a Resource object. If you’re writing code that takes a Resource object as an argument and performs some action, that argument would require the Resource<T> type.

`WritableResource<T>` Interface

The WritableResource<T> interface extends Resource<T>, with the difference being that it supports writes. The value field is of type WritableSignal<T>, and it also provides set and update methods. You can also convert it to a read-only Resource<T> using the asReadonly method. Additionally, the reload method re-executes the last resource resolution, which also updates the value internally. In essence, WritableResource<T> allows the user to trigger value updates.

export interface WritableResource<T> extends Resource<T> {
  readonly value: WritableSignal<T>;

  set(value: T): void;
  update(updater: (value: T) => T): void;
  asReadonly(): Resource<T>;
  reload(): boolean;
}

`ResourceSnapshot<T>` Interface

The ResourceSnapshot<T> interface represents an immutable object that captures the internal state of a Resource object at a specific moment. Specifically, it includes a status field indicating the resolution state of the Resource, and additional fields corresponding to each status. While a Resource is an object whose state changes asynchronously, that state always follows a so-called Discriminated Union type that falls into one of these snapshot types.

export type ResourceSnapshot<T> =
  | {readonly status: 'idle'; readonly value: T}
  | {readonly status: 'loading' | 'reloading'; readonly value: T}
  | {readonly status: 'resolved' | 'local'; readonly value: T}
  | {readonly status: 'error'; readonly error: Error};

The snapshot field of Resource<T> is related in that it returns the state at the time of calling as a ResourceSnapshot<T> type object.

`resourceFromSnapshots` Function

The fact that the possible states of Resource<T> can always be extracted as ResourceSnapshot<T> means that the continuous changes of ResourceSnapshot<T> are what define the Resource<T> itself. In other words, a Resource<T> is a Signal<ResourceSnapshot<T>>.

The resourceFromSnapshots function expresses this directly. It takes a function that returns a ResourceSnapshot<T> as an argument. If the argument is a Signal<ResourceSnapshot<T>>, it is subscribed to internally and automatically reflected in the state of the Resource<T>. Since the source is the source of truth for the state, what’s returned is a read-only Resource object.

function resourceFromSnapshots<T>(
  source: () => ResourceSnapshot<T>,
): Resource<T>;

  const source = signal<ResourceSnapshot<string>>({status: 'idle', value: ''});
  const res = resourceFromSnapshots(source);
  expect(res.status()).toEqual('idle');
  expect(res.value()).toEqual('');
  expect(res.isLoading()).toBeFalse();
  expect(res.hasValue()).toBeTrue();

  // Update snapshot
  source.set({status: 'loading', value: 'alpha'});
  expect(res.status()).toEqual('loading');
  expect(res.value()).toEqual('alpha');
  expect(res.isLoading()).toBeTrue();
  expect(res.hasValue()).toBeTrue();

You’re completely free to decide how to create the source Signal—it could be via the signal function, the input function, linkedSignal, or computed. As long as it ends up as a Signal<ResourceSnapshot<T>>, it’s fine. If you’re creating a Resource object for a specific purpose, this method is quite handy. Of course, if the built-in factory APIs I’ll mention later suffice, those are fine too.

`resource` Function

The resource function is a built-in Resource factory API. Unlike the resourceFromSnapshots function, it returns a writable Resource object based on declarative options. ResourceRef<T> is almost the same as WritableResource<T>.

function resource<T, R>(
  options: ResourceOptions<T, R> & { defaultValue: NoInfer<T> },
): ResourceRef<T>;

I’ll skip the details of how to use the API since you can find that in the documentation, but broadly speaking, you can construct a Resource object in two ways. One is by using a Loader that returns a Promise, and the other is by using a Loader that returns a Stream. By Stream, I mean a sequence of values—specifically, a Signal<ResourceStreamItem<T>>. ResourceStreamItem<T> specifically refers to {value: T} | {error: Error}.

const userId: Signal<string> = getUserId();

// Promise-based Loader
const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}): Promise<User> => fetchUser(params),
});

// Signal-based Streaming Loader
const chunkedMessageResource = resource({
  params: () => ({id: messageId()}),
  stream: ({params}): Signal<ResourceStreamItem<string>> => {
    const message = signal<string>('');
    chunkedMessage(params).subscribe({
      next: (chunk) => {
        message.update(item => ({ value: item.value + chunk }));
      },
      error: (err) => message.set({ error: err }),
    });
  },
});

If you have a use case that requires multiple value writes rather than a Promise model where resolution finishes once, you can configure it with a Stream-based Loader. However, for this use case, I think resourceFromSnapshots, mentioned earlier, is generally more versatile and easier to use, and personally, I think it wouldn’t be surprising if this eventually disappeared. Unless there’s a specific reason, I think it’s best to limit the use of the resource function to when you have a Promise-based Loader.

`httpResource` Function

The final one, httpResource, is a built-in Resource factory API like the resource function, but its purpose is more specific. As the name suggests, it’s a factory for constructing a Resource that resolves its value via HTTP requests. It takes a function that resolves a url, and you can obtain the response fetched internally using Angular’s HttpClient as a Resource object. Since its purpose is clear, you shouldn’t have trouble deciding when to use it over other Resource factories.

function httpResource<T>(
  url: (ctx: ResourceParamsContext) => string | undefined, 
  options: HttpResourceOptions<T, unknown> & { defaultValue: NoInfer<T>; }
): HttpResourceRef<T>;

const userId = signal<string>('id');
const user = httpResource(() => `/api/user/${userId()}`);

The HttpResourceRef<T> interface adds HTTP-specific states to WritableResource<T>. Since value is managed by WritableResource<T>, it is read-write, but response headers and status codes are read-only. Also, note that calling asReadonly will turn it into a plain Resource<T>, causing any HTTP-specific information to be lost.

export interface HttpResourceRef<T> extends WritableResource<T>, ResourceRef<T> {
  readonly headers: Signal<HttpHeaders | undefined>;
  readonly statusCode: Signal<number | undefined>;
  readonly progress: Signal<HttpProgressEvent | undefined>;
}

Summary

I’ve summarized the relationships among the main APIs covered so far. Centered around Resource<T>, derived interfaces and their corresponding factory functions are provided out of the box. At the same time, implementations for these interfaces are interchangeable. The built-in factory APIs are not anything special; they are open so that you can create implementations specialized for individual use cases. I think keeping these relationships in mind will help you master the Resource API.

Angular v22: Lazy Loading Business Logic with injectAsync

Suguru Inatomi — Sun, 21 Jun 2026 23:49:00 +0000

The injectAsync function added in Angular v22 provides a new option for improving loading speeds. I’ll introduce this new API while reviewing the lazy loading APIs that have existed until now.

`injectAsync`

The inject function used for dependency injection creates a static reference to the target being injected. Therefore, if the dependent side is included in the initial load JS, the side being depended upon will also increase the bundle size. In the following example, the ReportView component and the ReportExporter service are statically coupled, and their loading timing cannot be separated.

// Static import
import { ReportExporter } from './exporter';

@Component({...})
export class ReportView {
  // ReportView statically references ReportExporter
  exporter = inject(ReportExporter);

  export() {
    this.exporter.export();
  }
}

If ReportExporter is not a feature that is always used, we might want to keep only ReportView in the initial load and delay ReportExporter so it’s only loaded when the export button is pressed. That’s what injectAsync achieves. This function asynchronizes the injection of a specific service, allowing for bundle splitting and making the module lazy-loadable.

Following the example below, replace the reference to the ReportExporter service from a static import to a dynamic import in the argument of the injectAsync function. By doing this, the this.exporter field becomes a function that returns a reference to the service asynchronously when called. By await-ing the return value, you can use the service just as before.

@Component({...})
export class ReportView {
  // Dynamic import
  // ReportView dynamically references ReportExporter
  exporter = injectAsync(() => import('./exporter').then(m => m.ReportExporter));

  async export() {
    const exporter = await this.exporter();
    exporter.export();
  }
}

Usage Constraints

Only services declared with @Injectable({ providedIn: 'root' }) or the @Service() decorator can use injectAsync. Because they are integrated into the dependency injection system dynamically as modules are loaded, complex provider definitions are not supported.

Lazy Loading Methods and Use Cases

As in the example above, if a portion of the features provided by an application is infrequently used, it’s worth considering lazy loading to avoid compromising the experience for users who don’t use those features. Angular provides several lazy loading APIs, but how to choose between them depends on the application domain—specifically, what granularity and at what boundaries the application’s features can be divided.

Lazy Loading via Routes

The largest granularity for lazy loading is splitting bundles by the Router’s page loading unit (route). When you want to lazy load pages under a certain path together using parent-child route relationships, you can use loadChildren; when you want to lazy load a specific route, you can use loadComponent.

import { Routes } from '@angular/router';

export const routes: Routes = [
  {
    path: 'login',
    // Lazy load the login page
    loadComponent: () => import('./components/auth/login-page'),
  },
  {
    path: 'admin',
    // Lazy load the admin pages
    loadComponent: () => import('./admin/admin.component'),
    loadChildren: () => import('./admin/admin.routes'),
  },
];

In cases where accessible pages are clearly separated, such as by user permissions, introducing route-based lazy loading would likely be effective.

Lazy Loading Partial Views

Using the @defer block, parts of a component view can be made lazy-loadable. The view is loaded and initialized only when that area enters the viewport or when the user performs an action.

@defer {
  <large-component />
} @placeholder {
  <p>プレースホルダーコンテンツ</p>
}

This is an option when a specific component within a descendant view has a large impact on bundle size, and its display speed is not mission-critical. For example, calendar widgets or complex forms come to mind. The comment section of a blog post that isn’t part of the initial view would also be a prime candidate for this.

In cases where the frequency and timing of feature use vary depending on the screen area, lazy loading views with @defer would work effectively.

Lazy Loading Services

When a part of the logic, rather than the view, is deferrable, injectAsync, which I’ve introduced here, is the choice. If logic that uses a large third-party library is not needed for the initial load and its loading can be triggered when needed, that’s where injectAsync comes in.

Lazy Loading Modules

Finally, it’s a method often forgotten because it’s not an Angular API, but lazy loading at the module level can be achieved simply by using standard ES Module dynamic imports (import(...)). This is because dynamic imports are converted into lazy loading within the Angular CLI build process. If the target to be loaded is just a function, class, or constant, it doesn’t involve Angular’s dependency injection or component system, so using plain dynamic imports is sufficient.

You could split by the service that uses it—such as a library used only in specific use cases—or you could reference the service statically and then split by module inside it. This can be decided based on implementation preference. The only difference is whether the responsibility for asynchronous processing lies outside or inside the service. Personally, I think if injectAsync can cover it, that’s fine, but when complex DI provider definitions are required, I wonder if it might be better to combine it with module-level lazy loading as appropriate.

Summary

injectAsync enables bundle splitting and lazy loading at the service level by replacing DI references with dynamic imports.
It is limited to services declared with @Injectable({ providedIn: 'root' }) or @Service(), and does not support complex provider definitions.
Lazy loading methods and units provided by Angular:
- Routes: loadChildren / loadComponent
- Partial Views: @defer
- Services: injectAsync
- Other modules: import(...)

Angular: Implementing summaryResource to Signal-ize Built-in AI

Suguru Inatomi — Mon, 27 Apr 2026 07:49:00 +0000

I previously posted an article about enabling blog post summarization using the Summarizer API, which is a built-in AI feature in Chrome.

Summarize with built-in AI | AI on Chrome | Chrome for Developers

Distill lengthy articles, complex documents, or even lively chat conversations into concise and insightful summaries.

developer.chrome.com

ブログに記事要約機能を実装した（Built-in AI on Chrome） | lacolaco's marginalia

blog.lacolaco.net

This time, I tried an implementation that wraps the asynchronous processing of this Summarizer API with Angular’s Resource API for use within an Angular application. Let’s try calling the Summarizer API reactively in a way that links with the application state managed by Signals.

You can see a working sample on StackBlitz. Note that since only Chrome currently supports the Summarizer API, it will not work in browsers other than Chrome.

stackblitz.com

Prototype: `summaryResource`

First, I’ll introduce the interface of the final version, summaryResource. In the following App component, the summaryResource function is called with the input string signal bound to a textarea as an argument. The returned SummaryResource provides the Summarizer API status as a summary.summarizerAvailability() status signal and the summarized result of the input content as a summary.value() string signal.

import { Component, signal } from '@angular/core';
import { debounce, form, FormField } from '@angular/forms/signals';
import { summaryResource } from './summarized.resource';

@Component({
  selector: 'app-root',
  imports: [FormField],
  template: `
    <div>
      <h1>Built-in AI Summarizer</h1>

      <div>
        <div>
          <label for="input-text">入力テキスト</label>
        </div>
        <textarea
          id="input-text"
          [formField]="inputForm"
          placeholder="要約したい長文をここに貼り付け"
        ></textarea>
      </div>

      <section>
        @switch (summary.summarizerAvailability()) {
          @case ('unavailable') {
            <p>要約機能は利用できません。</p>
          }
          @case ('downloadable') {
            <button type="button" (click)="summary.initialize()">
              要約機能を初期化
            </button>
          }
          @case ('downloading') {
            <p>要約機能をダウンロード中…</p>
          }
          @case ('available') {
            @switch (summary.status()) {
              @case ('idle') {
                <p>テキストを入力すると要約が表示されます。</p>
              }
              @case ('loading') {
                <p>要約しています…</p>
              }
              @case ('error') {
                <p>{{ summary.error()?.message }}</p>
              }
              @case ('resolved') {
                <p>{{ summary.value() }}</p>
              }
            }
          }
        }
      </section>
    </div>
  `,
})
export class App {
  protected readonly input = signal('');
  readonly inputForm = form(this.input, (control) => {
    debounce(control, 500);
  });

  protected readonly summary = summaryResource(this.input, {
    summarizerOptions: {
      outputLanguage: 'ja',
    },
  });
}

It hides the internal asynchronous processing with a mental model similar to Angular’s built-in httpResource, and is able to represent the result of asynchronous processing for dynamic values using the Resource type.

From here, I will explain how this summaryResource is constructed.

Summarizer API

I’ve already introduced this in the aforementioned article, and since I’d like you to refer to the official documentation for the latest information, I won’t go too deep into the details of the Summarizer API itself. First, we create a function to call the Summarizer API directly from the application. In the following code, I wrote a function that wraps the detection of whether the Summarizer variable even exists in the execution environment and the calls to Summarizer.availability and Summarizer.create. This allows other parts of the application to remain unaware of the details of how to call the Summarizer API.

// ai/summarizer.ts
export const isSummarizationSupported = 'Summarizer' in self;

export async function getBuiltinAISummarizerAvailability(
  options?: SummarizerCreateCoreOptions,
): Promise<Availability> {
  if (!isSummarizationSupported) return 'unavailable';
  return Summarizer.availability(options);
}

export async function createBuiltinAISummarizer(
  options: SummarizerCreateOptions = {},
): Promise<Summarizer> {
  const availability = await getBuiltinAISummarizerAvailability(options);
  if (availability === 'unavailable') {
    throw new Error('Summarizer API is unavailable on this device.');
  }
  return Summarizer.create(options);
}

SummarizerFactory

This isn’t the essential part of this topic, but it’s a necessary piece for handling environment differences to use the Built-in AI feature in practice. I’ve set it up to switch via DI so that it swaps to a Noop implementation that summarizes nothing in environments where the Summarizer API is unavailable. Of course, it also serves as a hook point that can be replaced with any Summarizer implementation during testing.

// summarizer-factory.ts
import { Injectable } from '@angular/core';
import {
  createBuiltinAISummarizer,
  getBuiltinAISummarizerAvailability,
  isSummarizationSupported,
} from './ai/summarizer';

@Injectable({
  providedIn: 'root',
  useFactory: () =>
    isSummarizationSupported ? new BuiltinAISummarizerFactory() : new NoopSummarizerFactory(),
})
export abstract class SummarizerFactory {
  abstract availability(options?: SummarizerCreateCoreOptions): Promise<Availability>;
  abstract create(options?: SummarizerCreateOptions): Promise<Summarizer>;
}

@Injectable()
export class BuiltinAISummarizerFactory extends SummarizerFactory {
  override availability(options?: SummarizerCreateCoreOptions): Promise<Availability> {
    return getBuiltinAISummarizerAvailability(options);
  }

  override create(options?: SummarizerCreateOptions): Promise<Summarizer> {
    return createBuiltinAISummarizer(options);
  }
}

@Injectable()
export class NoopSummarizerFactory extends SummarizerFactory {
  override async availability(): Promise<Availability> {
    return 'available';
  }

  override async create(): Promise<Summarizer> {
    // Minimal stub for environments without Built-in AI API support / tests.
    return {
      summarize: async (input: string) => input,
      summarizeStreaming: () => new ReadableStream<string>(),
      destroy: () => {},
    } as unknown as Summarizer;
  }
}

SummaryResource

This is the body of the summaryResource function. It’s a bit complex, so let’s look at the parts one by one.

First, regarding the SummaryResource type that serves as the function’s return value. This adds two fields to the Resource<T> type provided by Angular. summarizerAvailability is, as the name suggests, a signal representing the availability status of the Summarizer instance itself. And the other, initialize, is a function to explicitly trigger the creation of the Summarizer instance.

/**
 * Resource returned by {@link summaryResource}.
 * Standard Resource<string> with Summarizer-specific properties added.
 */
export interface SummaryResource extends Resource<string> {
  /** Summarizer availability. Reflects the return value of Summarizer.availability(). */
  readonly summarizerAvailability: Signal<Availability>;

  /**
   * Creates a Summarizer and starts summarization. Idempotent.
   * When `summarizerAvailability()` is `'downloadable'`, it must be called from a user-initiated action (e.g., a click).
   */
  initialize(): void;
}

Why is initialize necessary? It’s because the AI model used internally by the Summarizer API is downloaded on-demand when needed, but the specification states that user activation is required to start that download. In other words, it cannot be started by events like page loading; it must be triggered by a user interaction event such as a button click.

If the device can support built-in AI APIs, but the model is not yet downloaded, the user must meaningfully interact with your page for your application to start a session with create().

Therefore, in summaryResource, I’ve added a conditional branch to automatically call initialize only when the result of calling factory.availability is available or downloading, as follows.

export const summaryResource = (
  source: () => string,
  options: {
    summarizerOptions?: SummarizerCreateOptions;
    injector?: Injector;
  } = {},
): SummaryResource => {
  const injector = options.injector ?? inject(Injector);
  const factory = injector.get(SummarizerFactory);
  const summarizerOptions = options.summarizerOptions;

  const state = signal<ResourceSnapshot<string>>({ status: 'idle', value: '' });
  const summarizerAvailability = signal<Availability>('unavailable');

  let initialized = false;

  const initialize = async () => {
    if (initialized) {
      return;
    }
    initialized = true;
    // ...
  }

  factory.availability(summarizerOptions).then((availability) => {
    if (availability === 'unavailable') {
      initialized = true;
      state.set({ status: 'idle', value: '' });
      return;
    }
    if (availability === 'available' || availability === 'downloading') {
      initialize();
    }
  });

  return {
    ...resourceFromSnapshots(state),
    summarizerAvailability,
    initialize,
  };
};

Next, regarding the creation of the Summarizer instance. As shown below, in the initialize function, the factory.create function is called to create the Summarizer instance. This factory.create function’s Promise will wait for the model download. In other words, by the time the Promise resolves, summarizerAvailability is available.

Also, in coordination with the destruction of the Resource, I am using DestroyRef to perform the instance destruction of the Summarizer. This prevents unintended memory leaks.

export const summaryResource = (
  source: () => string,
  options: {
    summarizerOptions?: SummarizerCreateOptions;
    injector?: Injector;
  } = {},
): SummaryResource => {
  const injector = options.injector ?? inject(Injector);
  const destroyRef = injector.get(DestroyRef);
  const factory = injector.get(SummarizerFactory);
  const summarizerOptions = options.summarizerOptions;

  const state = signal<ResourceSnapshot<string>>({ status: 'idle', value: '' });
  const summarizerAvailability = signal<Availability>('unavailable');

  let initialized = false;
  let activeSummarization: Promise<string> | null = null;

  const initialize = async () => {
    if (initialized) {
      return;
    }
    initialized = true;

    const summarizer = await factory.create(summarizerOptions);
    summarizerAvailability.set('available');
    destroyRef.onDestroy(() => {
      summarizer.destroy();
    });
  };

  return {
    ...resourceFromSnapshots(state),
    summarizerAvailability,
    initialize,
  };
};

Finally, the implementation of the part that reactively summarizes the input text. In the following code, an effect is declared inside the initialize function. This effect subscribes to the source signal, and whenever source is updated, this function is re-executed. If the input text is not empty, it calls the summarizer.summarize function to generate a summary. Since this summarization process takes time, there is a possibility that the input text has been updated while it is summarizing. The key point is that I’ve implemented state management with an activeSummarization variable, as well as cancellation processing using an AbortController and the onCleanUp function, so that old summaries are not processed unnecessarily.

export const summaryResource = (
  source: () => string,
  options: {
    summarizerOptions?: SummarizerCreateOptions;
    injector?: Injector;
  } = {},
): SummaryResource => {
  const injector = options.injector ?? inject(Injector);
  const destroyRef = injector.get(DestroyRef);
  const factory = injector.get(SummarizerFactory);
  const summarizerOptions = options.summarizerOptions;

  const state = signal<ResourceSnapshot<string>>({ status: 'idle', value: '' });
  const summarizerAvailability = signal<Availability>('unavailable');

  let initialized = false;
  let activeSummarization: Promise<string> | null = null;

  const initialize = async () => {
    //...

    effect(
      (onCleanUp) => {
        const input = source();
        if (!input.trim()) {
          state.set({ status: 'idle', value: '' });
          return;
        }

        const abortController = new AbortController();
        onCleanUp(() => {
          abortController.abort();
        });

        const summarizePromise = summarizer.summarize(input, { signal: abortController.signal });
        activeSummarization = summarizePromise;

        state.set({ status: 'loading', value: '' });
        summarizePromise
          .then((result) => {
            // Reflect only the latest Promise to avoid overwriting the new state with the results of an old summarize call.
            if (activeSummarization === summarizePromise) {
              state.set({ status: 'resolved', value: result });
            }
          })
          .catch((error) => {
            if (activeSummarization === summarizePromise) {
              state.set({ status: 'error', error });
            }
          });
      },
      { injector },
    );
  };

  //...

  return {
    ...resourceFromSnapshots(state),
    summarizerAvailability,
    initialize,
  };
};

By combining these, the summaryResource mentioned at the beginning is completed. If you want to read the entire source code, you can check it on StackBlitz or GitHub.

lacolaco / angular-built-in-ai

AngularBuiltInAi

This project was generated using Angular CLI version 21.2.8.

Development server

To start a local development server, run:

ng serve

Once the server is running, open your browser and navigate to http://localhost:4200/. The application will automatically reload whenever you modify any of the source files.

Code scaffolding

Angular CLI includes powerful code scaffolding tools. To generate a new component, run:

ng generate component component-name

For a complete list of available schematics (such as components, directives, or pipes), run:

ng generate --help

Building

To build the project run:

ng build

This will compile your project and store the build artifacts in the dist/ directory. By default, the production build optimizes your application for performance and speed.

Running unit tests

To execute unit tests with the Vitest test runner, use the following command:

ng test

Running end-to-end tests

For end-to-end (e2e) testing, run:

ng e2e

Angular CLI…

View on GitHub

Summary

I prototyped summaryResource to reactively handle the Summarizer API, a Chrome Built-in AI, using Angular’s Resource API and Signals.
SummaryResource extends Resource<string> and provides summarizerAvailability, which indicates the availability of the Summarizer, and initialize(), which is used to initialize from a user operation.
Since on-demand model downloading requires user activation, it is designed to either auto-initialize based on availability or have initialize() called explicitly from a button or similar.
In the implementation, I switched SummarizerFactory via DI to allow falling back to a Noop implementation in unsupported environments.
Input text summarization is subscribed to via effect, and by using an AbortController and a guard that only reflects the latest Promise, it follows input updates while avoiding unnecessary processing or conflicts.

Angular v22: Introducing ChangeDetectionStrategy.Eager and OnPush By Default

Suguru Inatomi — Wed, 22 Apr 2026 14:43:00 +0000

In Angular v21.2, ChangeDetectionStrategy.Eager was newly added as an option for a component’s change detection strategy. That said, this has exactly the same behavior as the existing ChangeDetectionStrategy.Default; it’s essentially just an alias.

As of v21, you can choose between Eager (= Default) and OnPush for the change detection strategy, but in v22, OnPush will finally become the default. A migration path for existing projects is also planned, so I’ll explain that here.

Default-to-Eager Migration

Through the ng update migration to Angular v22, components that have no strategy specified or are set to Default will be automatically rewritten to Eager. Because of this, applications in existing projects will continue to operate with the same change detection behavior as before, so no breaking changes should occur.

OnPush By Default

Starting from v22, the change detection strategy for components generated via ng new or ng generate will be OnPush by default. Of course, if you have explicitly set component generation options to changeDetection: Eager in your configuration files, that will be applied, but otherwise, new code will operate in OnPush mode without any extra effort.

Eager-to-OnPush Migration?

For now, there doesn’t seem to be any discussion about deprecating Eager mode. While OnPush has performance advantages, there is likely no need to rush the migration of existing code. When you do proceed with migration, it often goes smoothly if you first migrate the component’s internal state to a Signal. The primary reason a component stops working after switching to OnPush is when class fields are being modified internally, but if those fields are Signal instances, the template will automatically subscribe to changes in the Signal.

@Component({
  template: `
- <div>{{ userData?.name }}</div>
+ <div>{{ userData()?.name }}</div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class Component {
   private userService = inject(UserService);

- userData?: UserData | undefined;
+ readonly userData = signal<UserData | undefined>(undefined);

loadUserData() {
    this.userService.getUserData().then((data) => {
- this.userData = data;
+ this.userData.set(data);
    });
  }
}

The reason the Angular team wants to promote OnPush more than ever is that they want to encourage the “Zoneless-ification” of existing projects. To strip away the dependency on Zone.js, moving to OnPush is recommended. While not strictly required, if everything is running entirely on OnPush, you can guarantee that Zone.js is no longer needed. Conversely, if there are components running in Eager mode, the possibility of a dependency on Zone.js cannot be entirely ruled out.

The Angular MCP Server also provides a tool called onpush_zoneless_migration to assist with OnPush migration and going Zoneless using AI agents.

Even though existing code will continue to work as is, I expect the future Angular ecosystem will evolve with the general assumption that “OnPush is the default.” If you want to receive those benefits without exception, then the path toward OnPush and Zoneless migration will likely be an unavoidable one.

Summary

In Angular v22, ChangeDetectionStrategy.Eager is treated as the successor to Default.
For existing code, components set to Default or with no strategy specified will be automatically migrated to Eager via ng update, preserving their behavior.
Newly created components will use OnPush by default.
There is no need to migrate existing Eager components immediately, but the ecosystem will likely shift toward an OnPush prerequisite in the future.

Angular v22: Explaining debounced Resource

Suguru Inatomi — Wed, 08 Apr 2026 02:03:00 +0000

In Angular v22, it looks like debounced will be newly added to the Signals API family. I’ll explain the use cases and the mechanism for this API.

`debounced()`

The debounced function returns a Resource object with a certain wait time when changes to the source Signal are high-frequency. After a change to the source occurs, the value is finalized if no additional changes happen during the wait time. The mental model is similar to debounce in jQuery or RxJS.

export function debounced<T>(
  source: () => T,
  wait: NoInfer<number | ((value: T, lastValue: ResourceSnapshot<T>) => Promise<void> | void)>,
  options?: NoInfer<DebouncedOptions<T>>,
): Resource<T>

The following pseudo-code illustrates the behavior. While a Signal is a data model that always returns values synchronously, what the debounced function returns is a Resource object. Its value property returns a Signal that doesn’t change during the wait time. During the wait time, the isLoading property of the Resource will also be true.

const source = signal('initial');
const res = debounced(source, 200);

source(); // => initial
res.value(); // => initial
res.isLoading(); // => false

source.set('updated');
source(); // => updated
res.value(); // => initial
res.isLoading(); // => true

tick(200);

source(); // => updated
res.value(); // => updated
res.isLoading(); // => false

The primary concrete use case will likely be integration with Signal Forms. In cases where an HTTP request is triggered based on a Signal bound to a text field, you’ll want to debounce the user’s input. For example, you can create an HTTP Resource that calls an API with the value after waiting for a 200ms interval from the username field input, like this:

const usernameForm = form(signal('foobar'));
const res = httpResource(() => `/api/users/${debounced(usernameForm.value, 200)}`);

A similar use case is asynchronous validation in Signal Forms. This has been added as a built-in feature where a debounce option is available in the validateHttp function, allowing for HTTP-based validation by debouncing form value updates. Internally, the debounced function is being called.

const usernameForm = form(
  signal('foobar'),
  (p) => {
    validateHttp(p, {
      request: ({value}) => `/api/check?username=${value()}`,
      debounce: 50, // Short debounce
      onSuccess: (available: boolean) => (available ? undefined : {kind: 'username-taken'}),
      onError: () => null,
    });
  },
  {injector},
);

I think this mostly explains what the debounced function is. From here, let’s look at its mechanism.

Mechanism

As in the example where I wrapped Firestore the other day, Resource is an interface, and you’re free to choose how to construct it. Even if you don’t use the built-in resource or httpResource functions, you can still create objects that follow the Resource interface. While the actual debounced function has a complex implementation including fine-grained error handling within the framework, let’s try to understand the mechanism by creating a simplified version of a debounced function ourselves.

First, as a base form, let’s create a function that returns a Resource that doesn’t do anything. From Angular v21.2 onwards, you can use the resourceFromSnapshots function to convert a Signal of a specific type into a Resource.

function debounced<T>(source: () => T): Resource<T> {
  const state = signal<ResourceSnapshot>({
    status: 'resolved',
    value: untracked(() => source()),
  });
  return resourceFromSnapshots(state);
}

With just this, changes to the source won’t propagate to the Resource. We need to use an effect to update the state when the source changes.

function debounced<T>(source: () => T): Resource<T> {
  const state = signal<ResourceSnapshot>({
    status: 'resolved',
    value: untracked(() => source()),
  });

  effect(() => {
    const changedValue = source();

    state.set({
      status: 'resolved',
      value: changedValue,
    });
  });

  return resourceFromSnapshots(state);
}

Next, we’ll introduce a wait time. By accepting an interval as an argument and passing it to setTimeout, we can delay reflecting the value in the state. While it’s delayed, we’ll keep the state in a loading status.

function debounced<T>(source: () => T, wait: number): Resource<T> {
  const state = signal<ResourceSnapshot>({
    status: 'resolved',
    value: untracked(() => source()),
  });

  effect(() => {
    const changedValue = source();

    setTimeout(()=> {
      state.set({
        status: 'resolved',
        value: changedValue,
      });
    }, wait);

    state.set({
      status: 'loading',
      value: state.value(),
    });
  });

  return resourceFromSnapshots(state);
}

Currently, it’s just delaying. If an additional change is triggered during the delay, we need to discard the ongoing wait time and wait for the value to stabilize again. To maintain this asynchronous state, let’s introduce local variables called activePromise and pendingValue. In the delayed callback via setTimeout, if the active matches, it means no additional changes occurred.

function debounced<T>(source: () => T, wait: number): Resource<T> {
  const state = signal<ResourceSnapshot>({
    status: 'resolved',
    value: untracked(() => source()),
  });

  effect(() => {
    const changedValue = source();

    const waiting = new Promise(resolve => {
      setTimeout(resolve, wait)
    });

    const activePromise = waiting;
    const pendingValue = changedValue;

    waiting.then(() => {
      // If there is an intervening change, activePromise will mismatch
      if (waiting === activePromise) {
        state.set({
          status: 'resolved',
          value: pendingValue,
        });
      }
    });

    state.set({
      status: 'loading',
      value: state.value(),
    });
  });

  return resourceFromSnapshots(state);
}

Now our simplified debounced function is complete. Although it differs from the actual framework implementation in the finer details, the basic design looks like this. The internals are simple, just managing state with a Promise and a timer.

What I’m trying to say is that creating a function that returns a Resource type is easy. When you want to integrate processing with asynchronicity into a Signal, the hurdle to creating your own is low, even if the built-in APIs don’t fit perfectly. One example of that was turning the Firestore Collection into a Resource in my previous post.

Summary

The debounced() function expected to be introduced in Angular v22 takes a high-frequency Signal as input and returns a Resource that finalizes the value once it has settled for a certain period.
Typical usage is “debouncing input,” such as HTTP Resources linked to form inputs or asynchronous validation in Signal Forms.
The key point of the implementation is monitoring input changes with an effect, managing the latest wait using a timer and a Promise, and updating the ResourceSnapshot to resolved when finalized.
Creating a function that returns a Resource type is not difficult. It’s a useful interface that can be used to integrate asynchronous data sources with Signal.

Building Browser Extensions with WXT + Angular

Suguru Inatomi — Mon, 12 Jan 2026 09:08:00 +0000

I created a starter template for developing browser extensions by combining WXT and Angular. You can efficiently develop extensions for multiple browsers including Chrome and Firefox using Angular’s latest features.

lacolaco / wxt-angular-starter

Browser extension starter template using WXT and Angular

WXT + Angular Starter

A browser extension starter template using WXT and Angular.

Features

Angular 21 with zoneless change detection
Tailwind CSS v4 for styling
WXT for cross-browser extension development
Vite 7 powered build system
TypeScript with strict mode

Quick Start

# Clone the repository
git clone https://github.com/user/wxt-angular-starter.git
cd wxt-angular-starter

# Install dependencies
pnpm install

# Start development server (Chrome)
pnpm dev

# Start development server (Firefox)
pnpm dev:firefox

Available Scripts

Script	Description
`pnpm dev`	Start dev server for Chrome
`pnpm dev:firefox`	Start dev server for Firefox
`pnpm build`	Build for Chrome
`pnpm build:firefox`	Build for Firefox
`pnpm zip`	Build and package for Chrome
`pnpm zip:firefox`	Build and package for Firefox
`pnpm compile`	Type-check without emitting

Project Structure

├── entrypoints/
│   ├── popup/          # Angular popup entrypoint
│   │   ├── index.html
│   │   ├── main.ts     # Angular bootstrap
│   │   ├── app.ts      # Root component
│   │   └── style.css

…

View on GitHub

What is WXT

https://wxt.dev/

WXT is a framework that streamlines browser extension development. Built on Vite, it provides a comfortable development experience with fast HMR (Hot Module Replacement) and a file-based manifest auto-generation system.

Particularly useful is its ability to generate extensions for multiple browsers including Chrome, Firefox, Edge, and Safari from a single codebase. It supports both Manifest V2 and V3, absorbing browser-specific differences.

Building Browser Extensions with Angular

For the UI part of browser extensions, you’ll be loading HTML. WXT officially supports several libraries. When you run the wxt init command, you can choose templates like Vanilla, React, or Vue, but there’s no Angular template yet. However, the setup isn’t too difficult - you can simply configure Angular on top of the Vanilla base.

Note that to run Angular with Vite, you need the @analogjs/vite-plugin-angular plugin. This plugin is provided by the AnalogJS project and enables Angular to work within the Vite ecosystem.

https://www.npmjs.com/package/@analogjs/vite-plugin-angular

Project Structure

The starter template has the following structure:

├── entrypoints/
│ ├── popup/ # Angular popup interface
│ │ ├── index.html
│ │ ├── main.ts # Angular bootstrap
│ │ ├── app.ts # Root component
│ │ └── style.css # Tailwind CSS
│ ├── background.ts # Background script
│ └── content.ts # Content script
├── wxt.config.ts # WXT configuration
├── tsconfig.json # Base TypeScript config
└── [tsconfig.app](http://tsconfig.app/).json # Angular-specific config

In WXT, manifests are automatically generated from files in the entrypoints directory. The popup directory serves as the entry point for the Angular application, while background.ts and content.ts can be written in plain TypeScript.

Setup Steps

Here are the steps to build from scratch.

1. Initialize WXT Project

First, create a WXT project:

pnpm dlx wxt@latest init my-extension
cd my-extension

2. Install Dependencies

Install Angular core and build tools:

# Angular core
pnpm add @angular/core @angular/common @angular/compiler @angular/platform-browser rxjs

# Build tools
pnpm add -D @analogjs/vite-plugin-angular @angular/build @angular/compiler-cli

# Tailwind CSS (optional)
pnpm add -D tailwindcss @tailwindcss/vite

3. Pin Vite Version

Since @analogjs/vite-plugin-angular requires Vite 7.x, pin the version in package.json:

{
  "pnpm": {
    "overrides": {
      "vite": "^7.3.0"
    }
  }
}

After adding this, run pnpm install to apply the version.

4. Configure WXT

Configure Vite plugins in wxt.config.ts:

import { defineConfig } from 'wxt';
import angular from '@analogjs/vite-plugin-angular';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  vite: () => ({
    resolve: {
      mainFields: ['module'], // Prioritize ESM
    },
    plugins: [
      angular({
        tsconfig: '[tsconfig.app](http://tsconfig.app/).json',
        // Limit Angular compilation to specific entrypoints
        transformFilter: (_code: string, id: string) => {
          return id.includes('/entrypoints/popup/');
        },
      }),
      tailwindcss(),
    ],
  }),
});

The key is the transformFilter configuration. This ensures that only files in the entrypoints/popup/ directory are processed by the Angular compiler. Background and content scripts are treated as plain TypeScript, allowing coexistence of code that doesn’t use Angular.

5. Configure TypeScript

Separate project-wide configuration from Angular-specific configuration.

tsconfig.json (project-wide):

{
  "extends": "./.wxt/tsconfig.json",
  "compilerOptions": {
    "experimentalDecorators": true,
    "useDefineForClassFields": false
  },
  "angularCompilerOptions": {
    "strictInjectionParameters": true,
    "strictInputAccessModifiers": true,
    "strictTemplates": true
  }
}

tsconfig.app.json (Angular-specific):

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "lib": ["ES2022", "DOM"],
    "strict": true,
    "experimentalDecorators": true,
    "useDefineForClassFields": false,
    "skipLibCheck": true,
    "isolatedModules": true
  },
  "angularCompilerOptions": {
    "strictInjectionParameters": true,
    "strictInputAccessModifiers": true,
    "strictTemplates": true
  },
  "include": ["entrypoints/popup/**/*.ts"]
}

The include limits the files processed by the Angular compiler. If you want to use Angular in other entrypoints like options pages, add them here.

6. Create Angular Popup

Finally, create the entry point for the Angular application.

entrypoints/popup/index.html:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My Extension</title>
    <meta name="manifest.type" content="browser_action" />
  </head>
  <body>
    <app-root></app-root>
    <script type="module" src="./main.ts"></script>
  </body>
</html>

entrypoints/popup/main.ts:

import './style.css';
import { bootstrapApplication } from '@angular/platform-browser';
import { provideZonelessChangeDetection } from '@angular/core';
import { App } from './app';

bootstrapApplication(App, {
  providers: [provideZonelessChangeDetection()],
}).catch((err: unknown) => console.error(err));

entrypoints/popup/app.ts:

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

@Component({
  selector: 'app-root',
  changeDetection: ChangeDetectionStrategy.OnPush,
  host: { class: 'block p-4' },
  template: `
    <h1 class="text-lg font-bold">Hello from Angular!</h1>
  `,
})
export class App {}

entrypoints/popup/style.css:

@import 'tailwindcss';

Since we’re now on Angular v21, I’m using provideZonelessChangeDetection() to enable change detection without Zone.js. In limited environments like browser extensions, Zone.js overhead is often wasteful, so this reduces bundle size and minimizes runtime overhead.

Development and Build

Once setup is complete, you can start the development server:

# Chrome dev server
pnpm dev

# Firefox dev server
pnpm dev:firefox

For production builds and packaging:

# Chrome build
pnpm build

# Firefox build and ZIP
pnpm zip:firefox

Summary

Combining WXT and Angular enables modern browser extension development. The appeal is being able to leverage both WXT’s excellent developer experience and Angular’s powerful features. Using this starter template, you can start development immediately without the setup hassle.

The repository mentioned at the beginning is published as a GitHub template repository, so if you’re interested, click Use this template on the repository to create your own browser extension.

Understanding Angular Ivy Library Compilation

Suguru Inatomi — Wed, 24 Feb 2021 07:13:34 +0000

Original Post: https://blog.lacolaco.net/2021/02/angular-ivy-library-compilation-design-in-depth-en/

In this post, I will explain how to compile Angular libraries with Ivy, which is now possible in Angular v11.1, and its details. The intended audience is those who are developing Angular third-party libraries, or simply interested in Angular’s internal mechanism. You don’t need to know anything in this article to develop Angular applications.

The content of this article is based on the Design Doc written by the Angular team.

Ivy Library Compilation - Conceptual Design Doc

How to compile libraries with Ivy

When you develop an Angular library using Angular CLI or something similar, Ivy is currently disabled for production build. It is probably set in a file like src/tsconfig.lib.prod.json as follows.

{
  "angularCompilerOptions": {
    "enableIvy": false
  }
}

Angular libraries compiled and published to NPM with this configuration are still compatible for use even if the applications are not Ivy-enabled.

Starting from Angular v11.1, you can experimentally remove compatibility for applications not yet Ivy-enabled, and compile the library optimized for Ivy-enabled applications. To use Ivy compilation for libraries to be published to NPM, configure as follows

{
  "angularCompilerOptions": {
    "enableIvy": true,
    "compilationMode": "partial"
  }
}

"compilationMode": "partial" is an important part, and I will explain what it means in the later part of this post. Of course, libraries compiled with this setting can only be used in Ivy-enabled applications, so it is still not currently recommended.

By the way, for libraries that are only used locally in monorepo, such as Angular CLI and Nrwl/Nx, you can simply use enableIvy: true. The "compilationMode": "partial" is required only for the libraries that are published in NPM. This difference is also explained later in this article.

{
  "angularCompilerOptions": {
    "enableIvy": true
  }
}

Terminology

In order to make the following explanations concise, let’s first sort out the terminology.

term	meaning
Angular decorators	Decorators defined by Angular such as `@Component`, `@Directive`, and `@Injectable`.
Compiler	The Angular compiler is a tool that analyzes Angular decorators and generates executable code.
`ngc`	An executable CLI for the Angular compiler
Ivy compiler	A compiler introduced in Angular v9
View Engine (VE) compiler	A deprecated compiler that was used by default until Angular v8

Ivy compilation for applications

Before we start talking about libraries, let’s start with compiling an application with Ivy already enabled by default. The Angular decorator in the application will be analyzed by the compiler to generate the executable code based on the extracted metadata.

Let’s look at an example of compiling a simple component. Suppose we have the following component.

@Component([
  selector: 'some-comp',
  template: `<div> Hello! </div>`
})
export class SomeComponent {}

If you compile this code with Ivy, you will get the following JavaScript output. The two points are as follows

The decorator does not remain in the JavaScript.
The generated code is inserted as a static field in the component class.

export class SomeComponent {}
SomeComponent.ɵcmp = ɵɵdefineComponent({
  selectors: [['some-comp']],
  template: (rf) => {
    if (rf & 1) {
      ɵɵelementStart('div');
      ɵɵtext(' Hello! ');
      ɵɵelementEnd();
    }
  },
});

The Ivy compiler generates the code to create the definition from the metadata contained in the decorator. The HTML template, which was a string, becomes executable code as a Template Function. The ɵɵelementStart and ɵɵtext used in the template functions are called Template Instructions , and abstract the concrete DOM API calls and data binding update process.

Angular compilation is internally divided into two steps; Analysis step and code generation step.

Analysis step

In the analysis step of compilation, it integrates the metadata obtained from the decorators of the entire application and detects the dependencies between components/directives. At this point, the important part is the @NgModule. It is used to determine the references corresponding to unknown HTML tags and attributes contained in templates. After the analysis step, the compiler gets the following information.

Which components depend on which directives/components
What dependencies are needed to instantiate each component/directive

Code generation step

In the code generation step, it generates the code for each Angular decorator based on the information obtained in the analysis step. The generated code has two requirements: Locality and Runtime Compatibility.

Locality

Locality is also expressed as self-contained. It means that all the references needed for compiling the component are included in the component class itself. This makes differential builds more efficient. To make it easier to understand, let’s look back at the issues in the pre-Ivy View Engine days without Locality.

The VE compiler generated code as a file named *.ngfactory.js which was independent of the original file. Angular executes this *.ngfactory.js at runtime, and the generated code refers to the original component class. This approach becomes problematic when a component depends on another component.

For example, when a component <app-parent> uses a template to call a component <app-child>, there is no reference from parent.component.ts to child.component.ts as a JavaScript module. This parent-child dependence is only visible between parent.component.ngfactory.js and child.component.ngfactory.js.

Since the direct compilation result, parent.component.js, does not refer to either child.component.js or child.component.ngfactory.js, it cannot determine when it needs to be recompiled. Therefore, ViewEngine had to recompile the entire application at each build time.

To solve this problem, the Ivy compiler generates the code as a static field of the class. In the generation code, the classes of the directives referenced in the template are included. This makes it easy to determine which files will be affected when that file is changed.

As you can see, with code generation with Locality, it is only necessary to recompile ParentComponent when itself or ChildComponent is changed.

// parent.component.js
import { ChildComponent } from './child.component';

ParentComponent.ɵcmp = ɵɵdefineComponent({
    ...
    template: function ParentComponent_Template(rf, ctx) {
        if (rf & 1) {
            ɵɵelement(2, "app-child");
        }
    },
    // Directives depended on by the template
    directives: [ChildComponent]
});

Runtime compatibility

Another important factor in code generation is runtime compatibility. This is not an issue when compiling an application, but it is critical for compiling a library.

In an application, the compiler version and the Angular runtime version basically match because the compilation is done at the same time in the application build. However, this is not the same for libraries.

For libraries published to NPM, it must be considered that the Angular version that compiles the library does not match the Angular version used by the application that uses the library at runtime. A big issue here is the compatibility of the Angular APIs called in the generated code. APIs that existed in the compile-time version may not exist in the runtime version of Angular, or their signatures may have changed. So, the rules for code generation must be determined by the Angular version of the runtime that executes it.

Libraries used locally within monorepo were Ivy compilable because as long as it is in monorepo, it is ensured that the library and the application have the same Angular version.

Library compilation

Here is the main topic. First, let’s look at compiling libraries with enableIvy: false, which is the current recommended setting for v11. Compiling a library with no Ivy is just inlining the metadata collected in the analysis step. The Angular decorator metadata is embedded in the static field as shown below.

The library compilation works to convert the metadata into a JavaScript representation that can be published to NPM. However, this is still a metadata and cannot be executed as a component when loaded into an application. It needs to be compiled again based on this metadata. Angular Compatibility Compiler , ngcc, is the tool to do it.

ngcc

As we don’t know whether the application side compiler is Ivy or VE, the only way to keep compatibility is to compile the library code on the application side. This is the reason why ngcc is run at application build time.

The compilation result of ngcc is the same as that of compiling the library directly. The difference is that ngc uses decorators in TypeScript as metadata, while ngcc uses .decorators in JavaScript as metadata.

Although ngcc achieved its purpose to allow libraries to be released to NPM with compatibility, the frequent compilations spoiled the developer experience. Many of you may have felt the frustration of running ngcc repeatedly every time you installed a library. The ngcc overwrites the library code in node_modules installed from NPM and compiles it, so if the contents of node_modules are changed by the npm install command, you have to recompile it.

But originally, ngcc is a temporary approach until the View Engine support is removed from applications. The Ivy library compiler, which will be explained below, is a new Ivy-native library compilation mechanism that solves the problems clarified by ngcc.

Ivy library compilation

The biggest issue with ngcc was the execution cost of the compilation on the application side. If ngcc was fast enough, we could have compiled the library just-in-time when the application was compiled, without persisting the compilation results in node_modules. The execution cost is high, so we want to reduce the number of times and save the results.

On the other hand, if we finish compiling the library before publishing it, we can build the application faster, but we lose runtime compatibility. The code generation step really needs to be done in the application’s Angular version.

So Ivy library compilation concept is a set of mechanism for running only the code generation step rapidly after library installation and mechanism for finishing the analysis step before NPM release. The first mechanism is called library linking , and the second mechanism is called Link-Time Optimization (LTO) compilation.

LTO compilation (Pre-Publish compilation)

LTO compilation, which is done before publishing to NPM, is a mechanism to complete only the analysis step of the entire compilation and embed the result in JavaScript. As mentioned in the Introduction, when the setting "compilationMode": "partial" is set, the compiler will perform LTO compilation of the library.

{
  "angularCompilerOptions": {
    "enableIvy": true,
    "compilationMode": "partial"
  }
}

The compiled JavaScript contains the following code. It looks similar to the normal compilation result, but the important thing is that the template is preserved as a string and it has Locality.

The information obtained from the analysis step is inlined as a declaration. It includes a list of directives on which it depends, and has a locality that allows it to execute the code generation step with only information in the file. And by deferring the code generation of template functions until they are linked, the library can ensure runtime compatibility.

Also, the Angular version of the LTO compilation is included. Even if the template is the same, it can be optimized at link time depending on the combination of both the version it is written in and the runtime version.

Linking libraries

An application that installs an LTO compiled library will link it at the building time just-in-time. The Linker , which does the linking, will generate code based on the declarations from the LTO compilation, and replace them with definitions that can be used by the application.

Unlike ngcc, which required analysis step, the linking process can be executed independently for each file thanks to Locality of LTO compilation, so it can work as a plugin in module resolution like webpack. In the Angular CLI build, it is implemented as a Babel plugin called AngularLinker.

Wrap-up

The new Ivy library compilation can be summarized as follows:

The library compilation is separated into two parts: before and after NPM release.
One is the LTO compile process that finishes the decorator analysis before publishing to NPM.
The other is the linking process, which completes the compilation of the library by generating code at application build time.

I hope this article will help you readers understand how new Ivy library compilation is designed, based on the differences between applications and libraries in compilation, and the issues of ngcc used today.

Angular: Using NgRx Store with Redux Toolkit 🚀

Suguru Inatomi — Wed, 16 Dec 2020 12:09:31 +0000

Original Post: https://blog.lacolaco.net/2020/12/angular-using-ngrx-with-redux-toolkit/

This article introduces the idea of combining NgRx Store, the de facto standard state management library for Angular applications, with the Redux Toolkit, a library from the Redux team.

I expect that this will eventually become the solid configuration for Angular applications.

What is the Redux Toolkit (RTK)?

If you are already familiar with the Redux Toolkit, you can find it in the following “NgRx Store with RTK” section.

The Redux Toolkit ( RTK ) is the official library of the Redux development team. It provides best practices that match real-world use cases to make it easier and more effective for anyone to use Redux. A major theme of RTK is the reduction of cumbersome boilerplate code that has frequently occurred in Redux in the past. You can get a good overview of this through the Redux Toolkit Basic Tutorial. It is recommended that you read through it first.

https://redux-toolkit.js.org/tutorials/basic-tutorial

The ability to create Actions, Action Creators, Reducers, etc. with creating functions is also effective in reducing the existing boilerplate, but the most important thing is the last createSlice function. Just by looking at the code sample, you can see that the API is quite different from the impression of Redux so far, and the amount of code can be reduced considerably.

https://redux-toolkit.js.org/tutorials/basic-tutorial#introducing-createslice

const counterSlice = createSlice({
  name: 'counter',
  initialState: 0,
  reducers: {
    increment: (state) => state + 1,
    decrement: (state) => state - 1,
  },
});

const store = configureStore({
  reducer: counterSlice.reducer,
});

document.getElementById('increment').addEventListener('click', () => {
  store.dispatch(counterSlice.actions.increment());
});

In the future, Redux will basically be based on this Slice. Most of the existing Redux logic should be able to be solved by createSlice(), unless you are using it in a very complex way.

This API is the standard approach for writing Redux logic. (https://redux-toolkit.js.org/api/createSlice)

The concept of Slice is a new one created by the Redux Toolkit, but its essence is not entirely new. Here is a detailed explanation of Slice.

The concept of Slice

“Slice” is an object that encapsulates the Reducer and Action Creators created under the namespace.

createSlice returns a “slice” object that contains the generated reducer function as a field named reducer, and the generated action creators inside an object called actions. (https://redux-toolkit.js.org/tutorials/basic-tutorial)

// Creating a slice
const counterSlice = createSlice({
  name: 'counter',
  initialState: 0,
  reducers: {
    increment: (state) => state + 1,
  },
});
// Auto-generated reducer and action creators
const { reducer, actions } = counterSlice;
actions.increment(); // => Action { type: 'counter/increment' }

If you are familiar with the Redux “ducks” pattern, you will feel a sense of déjà vu when you see Slice, which is the exact representation of the ducks pattern as a type of object. The ducks pattern can be easily implemented by simply exporting each property individually from the return value of createSlice().

Thanks to createSlice, we already have our action creators and the reducer right here in one file. All we have to do is export them separately, and our todos slice file now matches the common “ducks” pattern. (https://redux-toolkit.js.org/tutorials/intermediate-tutorial)

// ducks pattern exports
export const { increment } = counterSlice.actions;
export default counterSlice.reducer;

The reason why it is called “Slice” will become clearer when we apply multiple Slices to a single Store. To combine multiple Slices, we will continue to use the combineReducers function. The Slice is the combination of [name]: namedReducer in this combine step. Each slice is a thin layer of the whole reducer.

There have been various approaches to dividing the Reducer in this way, and the ducks pattern has been popular. It creates modules that are scoped by namespaces while ensuring atomic state updates through centralized state management infrastructure. The reason why RTK and createSlice() should be used is that it is easy and anyone can implement the scalable Redux best practices in the same way.

NgRx Store with RTK

Redux is a framework-agnostic library. But why NgRx Store is widely used for Angular app state management instead of plain Redux?

Because it’s easy to set up in Angular’s DI.
Because they want to manage state changes with RxJS (Observable)
Because they want to use TypeScript’s type checking
Because it requires less boilerplate code than plain Redux

RTK can also solve the needs of TypeScript-friendliness and simplicity of description, and it also has the sense of security of being a Redux official. So, by using NgRx Store with RTK, we can write state management logic that blends naturally into Angular applications while benefiting from the Redux ecosystem. This is the starting point of my idea, and I am confident that it will work.

`StoreModule.forFeature()` and Slice

In NgRx Store, you can create a “Feature State” by using StoreModule.forFeature() for lazy loading or simply for separation of concerns. For applications of a large size, it is common to modularize them into Feature States instead of managing everything in the Root State.

import counterReducer, { name as counterFeatureKey } from './state/counter';

@NgModule({
  imports: [StoreModule.forFeature(counterFeatureKey, counterReducer)],
})
export class CounterModule {}

To create a Feature State, you need a string that is the key to distinguish the Feature and a Reducer function corresponding to the Feature State. And as mentioned earlier, RTK’s Slice has the same information. In other words, Feature State and Slice are both APIs aimed at modularizing state management, and their essence is almost the same.

By the way, NgRx Store is a state management library for Angular, based on RxJS, but its core is strongly inspired by Redux.

Store is RxJS powered global state management for Angular applications, inspired by Redux. (https://ngrx.io/guide/store)

This is not only the idea but also the interface of Action and Reducer, the principle part of Redux, is the same. So the objects generated by RTK can be directly applied to NgRx Store. In other words, the key and Reducer required for the Feature State can be generated by Slice.

I will explain the implementation with a simple example. It is a small application, but it has everything you need to integrate NgRx Store with RTK.

0. Setup NgRx Store

First, we need to prepare StoreModule.forRoot() to make Store available to components and services. If it is fully modularized, there will be no reducer to pass to forRoot().

@NgModule({
  imports: [BrowserModule, StoreModule.forRoot({})],
  // ...
})
export class AppModule {}

1. Create a counter slice

The first thing to do is to create a Slice. Create counter/counter-slice.ts and use the createSlice() function to create a Slice object. That’s almost all the code for state management.

import { createSlice } from '@reduxjs/toolkit';

const counterSlice = createSlice({
  name: 'counter',
  initialState: {
    count: 0,
  },
  reducers: {
    increment: (state) => {
      state.count++;
    },
  },
});

2. Make a “ducks” module

Based on the Slice created in step 1, we will modularize the Slice according to the ducks pattern: default export for Reducer, named export for Action Creator and other objects. Using object destructuring, we can write like the following:

const {
  reducer,
  actions: { increment },
  name,
} = counterSlice;

export default counterSlice.reducer;
export { increment, name };

This is a preference, so if you don’t find the ducks pattern valuable, you can export the Slice object as is.

3.Setup `StoreModule.forFeature()`

We will use the object exported from counter-slice.ts to set the Feature State of NgRx. Just call StoreModule.forFeature() in counter.module.ts and pass the name and reducer of the Slice as follows:

import counterReducer, { name as counterFeatureKey } from './counter-slice';

@NgModule({
  imports: [StoreModule.forFeature(counterFeatureKey, counterReducer)],
  // ...
})
export class CounterModule {}

4. Creating a Feature selector

In the NgRx Store, it is common to use a Feature Selector to retrieve the Feature State from the Store. This time, counter-slice.ts itself will create and export a Feature Selector. The type of the Feature State managed by counterSlice can be retrieved using ReturnType<typeof reducer>, thanks to RTK’s strong type inference support.

export const selectFeature = createFeatureSelector<ReturnType<typeof reducer>>(
  name
);

5. Access to Feature State

Finally, refer to the Feature State from the component, dispatch an Action to update it, and you are done. The code in this area is not affected by the RTK.

import { createSelector, Store } from '@ngrx/store';
import * as counterSlice from './counter-slice';

@Component({
  selector: 'app-counter',
  template: `<button (click)="increment()">INCREMENT</button>:
    {{ counter$ | async }}`,
})
export class CounterComponent {
  constructor(private readonly store: Store<{}>) {}

  // Get state
  counter$ = this.store.select(
    createSelector(counterSlice.selectFeature, (state) => state.count)
  );

  increment() {
    // Update state
    this.store.dispatch(counterSlice.increment());
  }
}

Advantages and disadvantages

This is a brief summary of the advantages and disadvantages of using NgRx Store with RTK.

Advantage: minimized boilerplate

Compared to the bare Redux, utilities provided by NgRx such as createReducer and createAction simplify the description, while createSlice() reduces waste to the absolute minimum. It not only reduces the amount of code but also hides the combination of multiple APIs in just one createSlice(), which is very good in terms of ease of remembering how to use it.

// NgRx
import { createAction, createReducer } from '@ngrx/store';

export const increment = createAction('[Counter Component] Increment');
export const initialState = 0;

const _counterReducer = createReducer(
  initialState,
  on(increment, (state) => state + 1)
);

export function counterReducer(state, action) {
  return _counterReducer(state, action);
}


// Redux Toolkit
import { createSlice } from '@reduxjs/toolkit';

const counterSlice = createSlice({
  name: 'counter',
  initialState: 0,
  reducers: {
    increment: (state) => state + 1,
  },
});

Advantage: Redux Ecosystem

RTK will become a central part of the Redux ecosystem in the near future, and new projects derived from RTK are emerging. For example, the recently released RTK Query is an experimental library that automates the common Redux use case of fetching data and caching the response. RTK-based state management makes it easier to keep up with the evolution of the Redux ecosystem.

Disadvantage: Increased bundle size

The RTK comes with some middleware by default, so the bundle size should be larger than the plain NgRx Store. Tree-shaking will mitigate this, but the increment will not be zero.

Conclusion

I had the opportunity to introduce my idea on the interoperability between NgRx Store and RTK.

I put up an issue on the NgRx GitHub repository suggesting how to improve interoperability with RTK, and the NgRx maintainer was very positive, and also Mark Erikson, the Redux maintainer, showed up and welcomed it.

https://github.com/ngrx/platform/issues/2809

// Detect dark theme var iframe = document.getElementById('tweet-1336804656777932803-373'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1336804656777932803&theme=dark" }

Since the RTK, the Redux ecosystem seems to be gaining momentum in spreading best practices that match real-world use cases. And I found out that there is an option to delegate the core of state management to the Redux official. I think the role of NgRx in combination with RTK will be to connect Redux with Angular’s DI system and reactive programming with RxJS as a bridge. And I believe that this division of responsibilities will become more important in the future.

The implementation example presented here is just one idea at the moment, and if you can find a better interoperable implementation pattern, I would love to see NgRx Store + RTK made by others. I’m looking forward to your feedback.

See you.

Angular: Eliminate Render Blocking Requests の概要

Suguru Inatomi — Thu, 01 Oct 2020 00:10:06 +0000

Originally published on blog.lacolaco.net.

この記事では Angular CLI チームで現在進行中の “Eliminate Render Blocking Requests” というプロジェクトについてその内容を解説する。一次ソースは以下のリンク先を参照されたし。

概要

このプロジェクトは Angular アプリケーションが依存する CSS について、 Render-Blocking な HTTP リクエストを無くそうというものである。 Render-Blocking なリソースの除去については web.dev の記事を参考にするとよい。

Eliminate render-blocking resources

最初のレンダリングに必要な CSS の読み込み時間がなくなることで First Contentful Paint（FCP）のパフォーマンスが改善される見込みだ。

Angular CLI チームが RFC（Request For Comments）で提案したのは次のような手法である。

CSS ファイルの読み込みの非同期化
Angular Universal SSR や Pre-rendering、App-Shell、通常のクライアントサイドレンダリングでのクリティカル CSS のインライン化
Google Fonts と Icons のインライン化

これらを Angular CLI で特別な設定無しに利用できるようにすることを目的としている。

背景

ng build コマンドのビルドに使われる styles の CSS ファイルは基本的にリセット CSS や Theming など、ページ表示の最初に読み込まれることが期待されている。しかし CSS は styles.css のような形でバンドルされ、 <link>タグで読み込むことになるため、この styles.css が肥大化するとページの First Contentful Paint（FCP）が遅くなる原因になる。とはいえ styles.css の内容をすべてインライン化するのは HTML ファイルのペイロードサイズを肥大化させてしまう。

そこで、本当にクリティカルな CSS だけをインライン化し、残りの部分を非同期化することで FCP を改善しようというのが今回の趣旨である。

解決案

これらの手法は Angular CLI に合理的な形で組み込めるかどうかはまだ保証できないが、現時点でのアイデアとして提案されているものであり、確定事項ではない。

CSS の非同期読み込み

バンドルされた styles.css が初期レンダリングに必要のないため CSS の読み込みを待たずにレンダリングを始めてよいことをブラウザに伝える。具体的には <link> タグの media 属性を使い、印刷などの特殊なユースケースを除いた通常のユースケースでは読み込みを非同期化する。

Before

<link rel="stylesheet" href="styles.css" />

After

<link
  rel="stylesheet"
  href="styles.css"
  media="print"
  onload="this.media='all'"
/>
<noscript><link rel="stylesheet" href="styles.css" /></noscript>

参考: レンダリングブロック CSS | Web | Google Developers

CSS Files Budget

CSS のダウンロードやパースの時間を短縮するため、ファイルサイズに関する新たな Budget を追加する。実際には参照されないデッドコードの除去や、グローバル CSS ではなく適切なコンポーネントのスタイルへの移動などを促進する。

anyStyle: 外部 CSS ファイル個別のサイズ
allStyle: すべての外部 CSS ファイルの累計サイズ

すでに存在するanyComponentSyle はコンポーネント CSS のファイルサイズを対象としているので全く別物である。

Google Fonts と Icons のインライン化

https://fonts.googleapis.com/ から最初にダウンロードするフォント読み込みの CSS をインライン化することで HTTP リクエストのラウンドトリップを削減する。これまでは CSS の読み込みのあとに woff などのフォントファイルの読み込みが行われていたが、フォントファイルの読み込みだけになる。また、Angular CLI が参照する browserslist の設定に基づいて最適なフォントフォーマットの決定も自動的に行われる。

Before

<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/icon?family=Material+Icons"
/>

After

<style>
  @font-face {
    font-family: 'Material Icons';
    font-style: normal;
    font-weight: 400;
    src: url(https://fonts.gstatic.com/s/materialicons/v55/flUhRq6tzZclQEJ-Vdg-IuiaDsNcIhQ8tQ.woff2)
      format('woff2');
  }

  .material-icons {
    font-family: 'Material Icons';
    font-weight: normal;
    font-style: normal;
    font-size: 24px;
    line-height: 1;
    letter-spacing: normal;
    text-transform: none;
    display: inline-block;
    white-space: nowrap;
    word-wrap: normal;
    direction: ltr;
  }
</style>

クリティカル CSS の抽出

Render-Blocking な CSS だけをインライン化するためには CSS を解析してその部分だけを抽出する必要がある。これをすでに実現しているプロジェクトとして、penthouseやcritters、criticalなどがある。これらはアプリケーションを一度レンダリングし、そこで参照されたクリティカル CSS を抽出する方法をとっている。

Google Chrome チームが開発している critters は抽出のためのレンダリングにヘッドレスブラウザではなく JSDOM を用いており、ビルド時だけでなくランタイムで動作させる選択肢としては上述のツールの中で最適であると考えられる。ただし、critters は viewport を予測せず、ドキュメントに読み込まれたすべての CSS をインライン化してしまうトレードオフがある。

また、Angular アプリケーションのユースケースにおいてそれぞれの課題を挙げている。

Angular Universal (SSR)

critters は webpack プラグインであるため、Node.js サーバー上で動的にビルドする Angular Universal は利用できない。したがって、Universal を考慮すれば critters のコア機能だけを Node.js 向けに切り出したものが必要になるだろう。うまく実現できれば、Universal でビルドした HTML の中にクリティカル CSS をインライン化してクライアントに返すことができる。

App-Shell / Pre-rendering

Angular CLI のビルド時にあらかじめ HTML をレンダリングする App-Shell や Universal Pre-rendering のユースケースについては、critters の基本的なアプローチで解決できる。

Client Side Rendering （CSR）

クライアントサイドレンダリングのアプリケーションは、Node.js 環境で実行できないため critters のようなツールでのクリティカル CSS 抽出ができない。しかし Angular コンテキストではないカスタムの CSS 読み込みは index.html で記述されることが多いため、ビルド時にこれらを抽出してインライン化することでこのケースをカバーする。

代替案

以下のアイデアは現時点では有用性が低い、実現可能性が低いなどの理由で採用される見込みの低いものである。

明示的なクリティカル CSS 定義

インライン化されるべきクリティカル CSS を開発者がアノテーションし、postcss-critical-splitのようなツールで抽出するアプローチ。このアプローチはその CSS がクリティカルであるかを開発者が判断しなければならないという問題と、サードパーティ CSS にはアノテーションできないという欠点があるため却下された。

/* critical:start */
header {
  background-color: #1d1d1d;
  font-size: 2em;
}

.aside {
  text-decoration: underline;
}
/* critical:end */

ヘッドレスブラウザによるクリティカル CSS 抽出

Penthouse はヘッドレス Chrome を使ってレンダリングしてクリティカル CSS を抽出するため、 Node.js で実行できない CSR のアプリケーションにも適用できる点で優れている。

ただしこのアプローチはランタイムで実行しなければならない Angular Universal のユースケースでパフォーマンスを落とすため却下された。

ルートコンポーネントでのグローバル CSS 読み込み

いわゆる AppComponent の styles を使ってグローバル CSS を読み込んでしまうことでコンポーネント CSS として Render-Blocking しない形でインライン化するアプローチ。

これは App-Shell や Pre-rendering のユースケースにおいて index.html が styles.css の内容をすべて含み肥大化してしまう欠点がある。

DNS-Prefetch と Preconnect Hints

Google Fonts と Icons の読み込みについて、DNS-Prefetch と Preconnect Hints を活用するアプローチ。欠点は特に無いが CSS のインライン化のほうがより効果的であると考えている。

RFC のフィードバック

RFC を通して集まったフィードバックのまとめは以下の通り。

この機能はデフォルトで有効であり、オプトアウト可能であるべき
新しい Size Budget は新プロジェクト、既存プロジェクトの両方に追加されるべき
CSS ファイルの Budget の追加にあたり、非利用 CSS の除去の手段も一緒に提供されることが望まれている

まとめ

リリース時期はまだ未定であるが、Angular アプリケーションのパフォーマンス改善のための大きなプロジェクトである。 v10 で導入された CommonJS インポート時の警告といい、Angular 特有のパフォーマンスというよりは web.dev で取り上げられるようなベストプラクティス的なパフォーマンス改善のアプローチを、Angular CLI のデフォルト機能としてサポートする取り組みに力が入っているようにも見える。

How CommonJS is making your bundles larger

Eliminate Render-Blocking Requests についてはゼロコンフィグ、あるいはほぼ設定不要で使えるべきであるという姿勢が強く見られるため、完成には時間がかかりそうではあるがぜひ期待したい。

Angular: Lightweight Injection Tokenという新しいテクニック

Suguru Inatomi — Wed, 29 Jul 2020 04:57:17 +0000

最近Angularチームが発見し、Angularライブラリの実装におけるパターンとして普及させようとしているのが、 Lightweight Injection Token というテクニックだ。これはこれまで不可能だった コンポーネント(ディレクティブ)のTree-Shaking を可能にする。本稿ではこの新しいテクニックの概要、そして生まれた経緯や深く知るための参考リンクをまとめる。

なお、Lightweight Injection Tokenについては公式ドキュメントでも解説される予定であるため、そちらを参照すればいい部分は省略する。

Angular - Optimizing client app size with lightweight injection tokens

Lightweight Injection Tokenの概要

ひとことでいえば、「オプショナルな機能に関連するInjection Tokenとして代替の軽量トークンを使う」ということである。AngularのDIを深く理解していればこれだけでピンと来るかもしれないが、具体例から概要をつかもう。

あるAngularライブラリが、次のような使い方ができる <lib-card> コンポーネントを提供している。

<lib-card>
  Hello World!
</lib-card>

このコンポーネントは、Contentとして <lib-card-header> コンポーネントを配置すると、カードのヘッダーとして取り扱う オプショナル な機能があることをイメージしよう。

<lib-card>
  <lib-card-header>Greeting Card</lib-card-header>
  Hello World!
</lib-card>

ライブラリ側はこのような使い方ができるコンポーネントを実装するとおおよそ次のようになるだろう。 @ContentChild() を使って CardHeaderComponent の参照を得る。ただしこのヘッダーを置くかどうかはユーザー次第なので、 CardHeaderComponent|null という形でnullを許容することになる。

@Component({
  selector: 'lib-card-header',
  ...,
})
class CardHeaderComponent {}

@Component({
  selector: 'lib-card',
  ...,
})
class CardComponent {
  @ContentChild(CardHeaderComponent)
  header: CardHeaderComponent|null = null;
}

ここで問題になるのが、 CardComponent から CardHeaderComponent への参照の持ち方である。 @ContentChild(CardHeaderComponent) と header: CardHeaderComponent|null の2箇所で参照を持っているが、この2つは性質が異なる。

後者の header: CardHeaderComponent|null は、型としての参照である。この参照はTypeScriptのコンパイル時型チェックにのみ用いられ、コンパイル後のJavaScriptには残らないため問題にならない。

問題は前者の @ContentChild(CardHeaderComponent) だ。これは値としての参照であり、 CardHeaderComponent というクラスオブジェクトそのものを参照している。それが直接 @ContentChild() デコレーターに渡されているのだから、 ユーザーがヘッダーを使おうが使わまいが、この参照は実行時に残る 。

@ViewChild() や @ContentChild() の走査条件として使われるコンポーネント/ディレクティブのクラス参照はどうしてもTree-Shakingできず、これがAngularライブラリを利用したときの バンドルサイズの肥大化の原因 となる。

これを解決するためのアプローチが、Lightweight Injection Tokenだ。上記の例で @ContentChild() デコレーターに渡していたクラスを、次のように軽量なオブジェクトを利用したInjection Tokenに置き換える。

// Lightweight Injection Token
abstract class CardHeaderToken {}

@Component({
  selector: 'lib-card-header',
  providers: [
    {provide: CardHeaderToken, useExisting: CardHeaderComponent}
  ]
  ...,
})
class CardHeaderComponent extends CardHeaderToken {}

@Component({
  selector: 'lib-card',
  ...,
})
class CardComponent {
  @ContentChild(CardHeaderToken) header: CardHeaderToken|null = null;
}

まず CardHeaderToken 抽象クラスを作成し、 CardHeaderComponent をその具象クラスとする。そしてコンポーネントプロバイダーで CardHeaderToken に対して自身のクラスオブジェクトを提供する。 CardComponent ではトークンを @ContentChild()デコレーターの走査条件とする。

これにより、 CardComponent から直接の CardHeaderComponent への参照はなくなり、ライブラリのユーザーが <lib-card-header> コンポーネントを呼び出したときだけ CardHeaderToken に対して CardHeaderComponent クラスのインスタンスが提供されることになる。

@ContentChild() や @ViewChild() の引数としてDIトークンを渡せるようになるのがバージョン 10.1.0からなので、このアプローチが取れるのは バージョン 10.1.0以降 になる（ as any で突破する手法はあるが）。

feat(core): support injection token as predicate in queries (#37506) · angular/angular@97dc85b

なぜ今なのか、これまでの経緯

この問題は昔からずっと存在したが、実はバージョン8まではそれほど重大な問題ではなかった。なぜかというとバージョン8以前、つまりIvy以前 (ViewEngine, VE) はAOTコンパイルによってテンプレートコンパイルされた結果の生成コードが、もとのコンポーネントとは別のクラス実体をもっていたからだ。

ViewEngineでは CardComponent クラスのデコレーターとそのメタデータをもとに CardComponentNgFactory クラスが生成される。そして、JavaScriptとしてコードサイズが大きいのはほとんどの場合NgFactory側である。

つまり上記の例でいえば、たとえ CardComponentNgFactory クラスが CardHeaderComponent への参照を持っていたとしても、CardHeaderComponent そのものが大きくないために問題にならなかったのだ。サイズが大きいのは CardHeaderComponenNgFactory のほうで、NgFactoryはテンプレート中で <lib-card-header> を使わない限り参照されないため、不完全ではあるがTree-ShakingできていたのがViewEngine方式だった。

バージョン9からデフォルトになったIvy方式のAOTコンパイルは、生成コードを もとのクラスの静的フィールドとして合成する 。よって AOTコンパイルすると CardHeaderComponent そのもののサイズが大きくなり、 CardComponent に巻き込まれて一緒にバンドルされるサイズが顕著に大きくなる。いままで行なわれていた生成コードのTree-ShakingがIvyによりなくなってしまった。

つまり、Lightweight Injection TokenはViewEngine時代には顕在化していなかったがIvyによってクリティカルになった問題を解決するために編み出された、 Ivy時代のAngualrライブラリ実装パターン である。

もっともポピュラーなAngularのコンポーネントライブラリであるAngular Materialではバージョン9リリース時からバンドルサイズの増加が報告されており、その解消の過程でAngularチームが辿り着いた答えである。現在Angular ComponentsチームはAngular Materialの各コンポーネントをLightweight Injection Tokenパターンに置き換える作業を進めている。

Increased initial main.js bundle size in v9 - mainly due to @angular/material packages · Issue #19610 · angular/components

Use light-weight injection pattern for optimized tree-shaking/bundle size · Issue #19576 · angular/components

コンポーネント以外のLightweight Injection Token

ところで、 @ContentChild() などの走査条件でなくとも、通常のDIの中でもオプショナルなものについてはLightweight Injection Tokenパターンを使うべきである。 @Optional() を使っていてもそのトークンの参照は残るためTree-Shakingはできない。コンストラクタDIでは型注釈部分にしか参照がないためコンパイルすれば消えそうに見えるが、コンストラクタ引数の型注釈はAOTコンパイル時に自動的に @Inject() デコレーターに変換されるため、実体参照をもつのである。つまりこれも @ContentChild() と全く同じ構造であり、同じ問題をもちうる。ライブラリ作者であればオプショナルなプロバイダーのトークンは可能な限り軽量にしておくべきだろう。

class MyComponent {
  constructor(@Optional() srv: OptionalService) {}
}

// Same
class MyComponent {
  constructor(@Optional() @Inject(OptionalService) srv: OptionalService) {}
}

ちなみにコンポーネントのLightweight Injection Tokenとして InjectionToken オブジェクトを使うこともできるはずだ。公式ドキュメントでは抽象クラスの例が紹介されているが、どちらが定着するかは今後のコミュニティでの受け入れられ方次第だろう。ただ、トークンの抽象クラスとコンポーネントクラスを継承関係にするとそのままコンポーネントのAPI定義として利用もできるため、おそらくは抽象クラスのほうが便利な場面は多そうだ。

const CardHeaderToken
  = new InjectionToken<CardHeaderComponent>("CardHeaderComponent");

https://angular.io/guide/dependency-injection-providers#non-class-dependencies

参考リンク

以下に参考リンクをまとめる。

Misko HeveryによるDesign Doc https://hackmd.io/@mhevery/SyqDjUlrU
公式ドキュメントへの追加PR https://github.com/angular/angular/pull/36144
Angular MaterialのIssue https://github.com/angular/components/issues/19576

Angular Elements: Composable Definition Pattern

Suguru Inatomi — Wed, 22 Jul 2020 01:59:46 +0000

Assuming a situation we have…

An Angular component library project, Lib1Module
An Angular Elements library project, Lib1ElementsModule
An Angular Elements library project, Lib2ElementsModule which uses Lib1ElementsModule

It can be achieved with loading scripts of both Lib1 and Lib2 separately. But composing multiple Angular Elements definition brings some benefits.

Unified Angular bootstrapping (better performance)
Single <script> tag in HTML (free from loading order problem)

Creating `Lib1ElementsModule`

import { createCustomElement } from '@angular/elements';

export function defineCustomElements(injector: Injector) {
  customElements.define(
    'lib1-button-element',
    createCustomElement(Lib1ButtonComponent, { injector })
  );
}

@NgModule({
  imports: [Lib1Module],
  // `entryComponents` is not needed if Ivy is enabled
  entryComponents: [Lib1ButtonComponent],
})
export class Lib1ElementsModule {
  constructor(private readonly injector: Injector) {}

  ngDoBootstrap() {
    defineCustomElements(this.injector);
  }
}

To use Lib1ElementsModule , bootstrap it directly. Then ngDoBootstrap() method will be called.

// main.elements.ts
platformBrowserDynamic().bootstrapModule(Lib1ElementsModule);

Creating `Lib2ElementsModule`

Lib2ElementsModule enables both Lib1 and Lib2 Angular Elements by composition.

import { createCustomElement } from '@angular/elements';
import {
  Lib1ElementsModule,
  defineCustomElements as defineLib1Elements,
} from 'lib1';

export function defineCustomElements(injector: Injector) {
  customElements.define(
    'lib2-card-element',
    createCustomElement(Lib2CardComponent, { injector })
  );
}

@NgModule({
  imports: [Lib2Module, Lib1ElementsModule],
  // `entryComponents` is not needed if Ivy is enabled
  entryComponents: [Lib2CardComponent],
})
export class Lib2ElementsModule {
  constructor(private readonly injector: Injector) {}

  ngDoBootstrap() {
    // Compose definition
    defineLib1Elements(this.injector);
    defineCustomElements(this.injector);
  }
}

Initial Null Problem of AsyncPipe and async data-binding

Suguru Inatomi — Wed, 19 Feb 2020 00:54:03 +0000

Original Post: https://blog.lacolaco.net/2020/02/async-pipe-initial-null-problem-en/

Angular's AsyncPipe is a useful feature for template binding of asynchronous data, but it has a big problem since the beginning. That is the "Initial Null Problem".
This article describes the Initial Null Problem of AsyncPipe and its root cause, and discusses new asynchronous data-binding to solve that.

I recommend you to see also this great article:

Handling Observables with Structural Directives in Angular - DEV Community 👩‍💻👨‍💻

How AsyncPipe works

AsyncPipe is now always used to create general Angular applications. It is often used to subscribe to Observable data and bind its snapshot to a template.
The basic usage is as follows.

@Component({
  selector: "app-root",
  template: `
    <div *ngIf="source$ | async as state">
      {{ state.count }}
    </div>
  `,
  styleUrls: ["./app.component.css"]
})
export class AppComponent {
  source$ = interval(1000).pipe(map(i => ({ count: i })));
}

So, how does AsyncPipe bind the value that source$ streams to a template and render it? Take a look at Implementation of AsyncPipe.

AsyncPipe has a lot of asynchronous data abstraction code that can handle both Promise and Observable, but the essential code is the following code. Like any other Pipe, it implements the transform() method.

  transform(obj: Observable<any>|Promise<any>|null|undefined): any {
    if (!this._obj) {
      if (obj) {
        this._subscribe(obj);
      }
      this._latestReturnedValue = this._latestValue;
      return this._latestValue;
    }

    if (obj !== this._obj) {
      this._dispose();
      return this.transform(obj as any);
    }

    if (ɵlooseIdentical(this._latestValue, this._latestReturnedValue)) {
      return this._latestReturnedValue;
    }

    this._latestReturnedValue = this._latestValue;
    return WrappedValue.wrap(this._latestValue);
  }

Let's look at the code from the top. The first if (!this._obj) is the condition when Observable is passed to AsyncPipe for the first time, that is, the initialization process. If this._obj doesn't exist and obj does, the pipe subscribes obj. obj corresponds to source$ in the example. The Observable passed to AsyncPipe is executed subscribe() here.

The next if statement is for when an Observable has changed from the one you are subscribing. It disposes the current subscription and starts resubscribing.

And the rest of the code is for returning the latest value this._latestValue from the subscribed Observable. The returned value will be the value actually used to render the template.

What you can see here is that AsyncPipe returns the cached this._latestValue when thetransform()method is called.
This can also be seen in AsyncPipe's _subscribe() and this._updateLatestValue() methods. When the value flows into the asynchronous data subscribed by the _subscribe() method, markForCheck() of ChangeDetectorRef is called in the callback. It causes the next transform() call.

  private _subscribe(obj: Observable<any>|Promise<any>|EventEmitter<any>): void {
    this._obj = obj;
    this._strategy = this._selectStrategy(obj);
    this._subscription = this._strategy.createSubscription(
        obj, (value: Object) => this._updateLatestValue(obj, value));
  }
  ...
  private _updateLatestValue(async: any, value: Object): void {
    if (async === this._obj) {
      this._latestValue = value;
      this._ref.markForCheck();
    }
  }

In other words, AsyncPipe renders templates using the following mechanism.

Pipe's transform() is called in Change Detection
Start subscribing to the passed Observable
Return this._latestValue at the time transform()is called
When Observable flows new data, update this._latestValue and trigger Change Detection (back to 1)

transform() must return a synchronous value, because the template can only render synchronous values. It can only return a cached snapshot at the time transform() is called.

A solid understanding of this should raise a question. That is, "at the start of the subscription, can't the transform() return a value?" And that is the biggest problem that AsyncPipe has, the "Initial Null Problem".

Initial Null Problem

Since this._latestValue is set by Observable's subscription callback, the value has never been set at the time of transform() call. However, transform() must return some value, so it returns a default value.
Let's look again at the beginning of AsyncPipe's transform().

    if (!this._obj) {
      if (obj) {
        this._subscribe(obj);
      }
      this._latestReturnedValue = this._latestValue;
      return this._latestValue;
    }

this._latestValue used in the last two lines has never been set, so the initial value of this field will be used. Its value is null.

export class AsyncPipe implements OnDestroy, PipeTransform {
  private _latestValue: any = null;
  private _latestReturnedValue: any = null;

In other words, AsyncPipe always returns null once before flowing the first value. Even if the original Observable is Observable<State>, it becomes State | null through AsyncPipe. This is a problem I call " Initial Null Problem".

While this problem seems serious, it has been automatically avoided in many cases. This is because *ngIf and *ngFor, which are often used with AsyncPipe, ignore the null returned from AsyncPipe.

In the following template, the value returned by source$ | async is evaluated by the NgIf directive, and if it is Truthy, it will be rendered, so if it is null, it will not go inside *ngIf.

<div *ngIf="source$ | async as state">
  {{ state.count }}
</div>

Similarly, in the following template, the value returned by source$ | async is evaluated by the NgFor directive and ignored if it is Falsey, so if it is null, it will not be inside *ngFor.

<div *ngFor="let item of source$ | async">
  {{ item }}
</div>

Through null-safe directives such as *ngIf and *ngFor, the Initial Null Problem does not affect the application. The problem is otherwise, that is, passing values directly to the child component's Input via AsyncPipe.
In the following cases, the child component should define a prop Input type, but you have to consider the possibility of passing null to it. If prop is a getter or setter, you can easily imagine a runtime error when trying to access the value.

<child [prop]="source$ | async"></child>

So far, one simple best practice can be said.
AsyncPipe should always be used through a null-safe guard like NgIf or NgFor.

Replace AsyncPipe

From here, I will explore the new asynchronous data-binding that can replace AsyncPipe which has the above-mentioned problem.

Why AsyncPipe returns null is Pipe needs to return a synchronous value. The only way to solve the Initial Null Problem is to stop using Pipe for async data.

So I tried using a directive. I think an approach that accepts an input and a template and renders the template under the control of the directive, is the best replacement for AsyncPipe.

So I implemented the *rxSubscribe directive. The sample that actually works is here. It subscribe an Observable with a structural directive as follows:

<div *rxSubscribe="source$; let state">
  {{ state.count }}
</div>

The directive is implemented as follows. What this directive does is

Subscribe an Observable received by rxSubscribe Input.
When the Observable value flows, embed (render) the template for the first time
When the value after the second time flows, update the context and call markForCheck()

https://github.com/lacolaco/ngivy-rx-subscribe-directive/blob/master/src/app/rx-subscribe.directive.ts

@Directive({
  selector: "[rxSubscribe]"
})
export class RxSubscribeDirective<T> implements OnInit, OnDestroy {
  constructor(
    private vcRef: ViewContainerRef,
    private templateRef: TemplateRef<RxSubscribeFromContext<T>>
  ) {}
  @Input("rxSubscribe")
  source$: Observable<T>;

  ngOnInit() {
    let viewRef: EmbeddedViewRef<RxSubscribeFromContext<T>>;
    this.source$.pipe(takeUntil(this.onDestroy$)).subscribe(source => {
      if (!viewRef) {
        viewRef = this.vcRef.createEmbeddedView(this.templateRef, {
          $implicit: source
        });
      } else {
        viewRef.context.$implicit = source;
        viewRef.markForCheck();
      }
    });
  }
}

With this approach, the template is not rendered until the value first flows, and re-rendering can be triggered only when the value flows. It solves the Initial Null Problem, and is also CPU-friendly because re-rendering is limited only when necessary.

By the way, the type of state in let stateis inferred from the type of source$ exactly if Ivy of Angular v9 or later, and if strictTemplates flag is enabled. When you make a mistake use of state, AOT compiler throws an error.

<div *rxSubscribe="source$; let state">
  {{ state.foo }}  <!-- compile error: state doesn't have `foo` -->
</div>

AsyncPipe could always only infer or null due to the Initial Null Problem, but the structure directive approach can infer the context type exactly from Observable<T>.

I've published this *rxSubscribe directive as the npm package @soundng/rx-subscribe.

Conclusion

AsyncPipe has Initial Null Problem
Guarding with NgIf or NgFor can avoid the initial null
Pipe has limitations in handling asynchronous data
Structural directive approach can solve AsyncPipe problem
Feedback welcome to @soundng/rx-subscribe

DEV Community: Suguru Inatomi

Angular: Resource API Family System Diagram

Resource API Family

Resource<T> Interface

WritableResource<T> Interface

ResourceSnapshot<T> Interface

resourceFromSnapshots Function

resource Function

httpResource Function

Summary

Angular v22: Lazy Loading Business Logic with injectAsync

injectAsync

Usage Constraints

Lazy Loading Methods and Use Cases

Lazy Loading via Routes

Lazy Loading Partial Views

Lazy Loading Services

Lazy Loading Modules

Summary

Angular: Implementing summaryResource to Signal-ize Built-in AI

Summarize with built-in AI | AI on Chrome | Chrome for Developers

ブログに記事要約機能を実装した（Built-in AI on Chrome） | lacolaco's marginalia

Prototype: summaryResource

Summarizer API

SummarizerFactory

SummaryResource

lacolaco / angular-built-in-ai

AngularBuiltInAi

Development server

Code scaffolding

Building

Running unit tests

Running end-to-end tests

Summary

Angular v22: Introducing ChangeDetectionStrategy.Eager and OnPush By Default

Default-to-Eager Migration

OnPush By Default

Eager-to-OnPush Migration?

Summary

Angular v22: Explaining debounced Resource

debounced()

Mechanism

Summary

Building Browser Extensions with WXT + Angular

lacolaco / wxt-angular-starter

Browser extension starter template using WXT and Angular

WXT + Angular Starter

Features

Quick Start

Available Scripts

Project Structure

What is WXT

Building Browser Extensions with Angular

Project Structure

Setup Steps

1. Initialize WXT Project

2. Install Dependencies

3. Pin Vite Version

4. Configure WXT

5. Configure TypeScript

6. Create Angular Popup

Development and Build

Summary

Understanding Angular Ivy Library Compilation

How to compile libraries with Ivy

Terminology

Ivy compilation for applications

Analysis step

Code generation step

Locality

Runtime compatibility

Library compilation

ngcc

Ivy library compilation

LTO compilation (Pre-Publish compilation)

Linking libraries

Wrap-up

Angular: Using NgRx Store with Redux Toolkit 🚀

What is the Redux Toolkit (RTK)?

The concept of Slice

`Resource<T>` Interface

`WritableResource<T>` Interface

`ResourceSnapshot<T>` Interface

`resourceFromSnapshots` Function

`resource` Function

`httpResource` Function

`injectAsync`

Prototype: `summaryResource`

`debounced()`

`StoreModule.forFeature()` and Slice

3.Setup `StoreModule.forFeature()`

Creating `Lib1ElementsModule`

Creating `Lib2ElementsModule`