Forem: Lars Gyrup Brink Nielsen

You don't need importProvidersFrom with Angular Material

Lars Gyrup Brink Nielsen — Tue, 18 Feb 2025 22:38:00 +0000

Cover photo generated with Microsoft Designer.

Traditionally, we had to import mixed Angular modules from Angular Material at the root level to provide services required for the following components.

Standalone Angular application

In Angular 14.0, the importProvidersFrom function was introduced with standalone application support in Angular. This allowed us to be more explicit about the reason for adding the Angular module import to the ApplicationConfig used with bootstrapApplication as seen in the following example.

import { ApplicationConfig, importProvidersFrom } from '@angular/core';
import { MatNativeDateModule, MAT_DATE_FORMATS } from '@angular/material/core';
import { MatDatepickerModule} from '@angular/material/datepicker';
import { MatDialogModule } from '@angular/material/dialog';
import { MatSnackbarModule } from '@angular/material/snack-bar';
import { MatTooltipModule } from '@angular/material/tooltip';
import { appDateFormats } from './app-date-formats';

export const appConfig: ApplicationConfig = {
  providers: [
    // Datepicker (and Timepicker)
    importProvidersFrom(MatDatepickerModule, MatNativeDateModule),
    { provide: MAT_DATE_FORMATS, useValue: appDateFormats },
    importProvidersFrom(MatDialogModule),
    importProvidersFrom(MatSnackbarModule),
    importProvidersFrom(MatTooltipModule),
  ],
};

app.config.ts example with Angular Material 14.0.

Classic Angular application

In an AppModule in a classic Angular application, it is less clear why we need to maintain these Angular module imports.

import { ApplicationConfig, importProvidersFrom, NgModule } from '@angular/core';
import { MatNativeDateModule, MAT_DATE_FORMATS } from '@angular/material/core';
import { MatDatepickerModule} from '@angular/material/datepicker';
import { MatDialogModule } from '@angular/material/dialog';
import { MatSnackbarModule } from '@angular/material/snack-bar';
import { MatTooltipModule } from '@angular/material/tooltip';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { AppComponent } from './app.component';
import { appDateFormats } from './app-date-formats';

@NgModule({
  declarations: [AppComponent],
  bootstrap: [AppComponent],
  imports: [
    // Angular Material
    BrowserAnimationsModule,
    // Datepicker (and Timepicker)
    MatDatepickerModule,
    MatNativeDateModule,
    { provide: MAT_DATE_FORMATS, useValue: appDateFormats },
    MatDialogModule,
    MatSnackbarModule,
    MatTooltipModule,
  ],
})
export class AppModule {}

app.module.ts example with Angular Material 13.3.

Standalone Angular Material providers

In recent Angular Material versions, we can leave out the following imports from our ApplicationConfig as the dependencies they provide are all tree-shakable (@Injectable({ providedIn: 'root' }) or InjectionToken with an inline provider).

As for the Datepicker and Timepicker dependencies, we can use the provideNativeDateAdapter function or a date-time library-specific date adapter like provideDateFnsAdapter as seen in the following example.

import { ApplicationConfig } from '@angular/core';
import { provideNativeDateAdapter } from '@angular/material/core';
import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';
import { appDateFormats } from './app-date-formats';

export const appConfig: ApplicationConfig = {
  providers: [
    provideAnimations(),
    // Datepicker (and Timepicker)
    provideNativeDateAdapter(appDateFormats),
  ],
};

app.config.ts example with Angular Material 17.1.

Much cleaner, right?

Benefits

Other than simpler application configuration code that is easier to reason about, we get the following benefits.

Smaller bundle size as the Angular Material service dependencies are loaded when a lazy-loaded chunk need them for the first time
Simpler component story configuration in Storybook as they can be simplified simlar to our ApplicationConfig as seen in the next section
Simpler component test configuration as it is simplified in a similar way as seen in a later section

Storybook component stories

In component stories, we use the applicationConfig Storybook decorator to add root-level providers.

import { provideNativeDateAdapter } from '@angular/material/core';
import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';
import { Meta, StoryObj, applicationConfig } from '@storybook/angular';
import { myDateFormats } from './my-date-formats';
import { MyMaterialComponent } from './my-material.component';

const meta: Meta<MyMaterialComponent> = {
  title: 'MyMaterialComponent',
  component: MyMaterialComponent,
  decorators: [
    applicationConfig({
      providers: [
        // Angular Material
        provideAnimationsAsync(),
        // Datepicker (and Timepicker)
        provideNativeDateAdapter(myDateFormats),
      ],
    }),
  ],
};

export default meta;
type Story = StoryObj<MyMaterialComponent>;

export const Default: Story = {};

my-material.component.stories.ts example with Angular Material 17.1.

In earlier versions of Angular Material, we had to use importProvidersFrom or pass the Angular modules to the imports option of thte moduleMetadata Storybook decorator.

Component tests

Angular Material depdendencies are also simpler to configure in component tests. When unit testing an Angular component, we configure root-level providers with the providers option for the TestBed.configureTestingModule method.

import { TestBed } from '@angular/core/testing';
import { provideNoopAnimations } from '@angular/platform-browser/animations';
import { myDateFormats } from './my-date-formats';
import { MyMaterialComponent } from './my-material.component';

it('MyMaterialComponent', () => {
  TestBed.configureTestingModule({
    providers: [
      // Angular Material
      provideNoopAnimations(),
      // Datepicker (and Timepicker)
      provideNativeDateAdapter(myDateFormats),
    ],
  });

  const fixture = TestBed.createComponent(MyMaterialComponent);

  expect(fixture.componentInstance).toBeDefined();
});

my-material.component.spec.ts example with Angular Material 17.1.

Conclusion

Modern Angular Material versions are easier to use, in part because of the standalone providers used for component dependencies since version 17.1. The following table shows the exact versions when each Angular Material component was converted to standalone providers.

Component	First version with standalone providers
Datepicker	`17.1.0`
Dialog	`17.0.0`
Snackbar	`17.0.0`
Timepicker	`19.0.0`
Tooltip	`15.0.4`

Root-level provider configuration for Angular Material components is easier to set up and reason about both in Angular applications, Storybook component stories, and Angular component tests.

Bundle sizes are optimized because of the tree-shakable providers.

Except for Date picker and Timepicker components, we don't have to remember to add any providers. Similarly, we don't have to remember to remove them if and when we remove all Angular Material component uses in an application, a component story, or a component test.

Historically, Angular and Angular Material progressed in the following way.

Add Angular modules to NgModule.imports for AppModule
Pass Angular modules to importProvidersFrom in ApplicationConfig.providers
No Angular modules but a provider function for the Datepicker and Timerpicker dependencies

Testing routed components with RouterTestingHarness

Lars Gyrup Brink Nielsen — Thu, 07 Dec 2023 00:00:00 +0000

Cover art by Microsoft Designer.

Since 2017, Angular documentation has offered little advice on testing routing components, routed components, routes, and route guards other than to create partial and brittle ActivatedRoute and Router test doubles.

While RouterTestingModule—recently replacable using the equivalent standalone APIs, provideRouter and provideLocationMocks—has been available since Angular version 2, documentation has been lacking at best.

In February 2023, Angular version 15.2 introduced RouterTestingHarness, the out-of-the-box experience for solving this 6 year old testing pain. The RouterTestingHarness sets up a testing root component with a RouterOutlet and uses the actual Angular Router API in our component tests.

In this article, we test and use parts of Angular.io's Tour of Heroes router tutorial.

To use the RouterTestingHarness, we first set up a test for a routing component or routed component using provideRouter as we would set up any standalone Angular application or feature.

TestBed.configureTestingModule({
  providers: [
    provideRouter([
      {
        path: 'superhero/:id',
        component: HeroDetailComponent,
      },
    ]),
    provideLocationMocks(),
  ],
});

We could provide just enough test routes for our component test as seen in the previous code listing or even use—and thereby test—our real feature routes. Exercising the actual routes as part of our component tests is one part of what I call Angular feature tests.

💡 Tip
We use provideLocationMocks to replace the Location and LocationStrategy services used internally by the Angular Router with test doubles to isolate the tests from browser History and Location APIs that would trigger navigation in test runners with a real browser environment like Karma, Web Test Runner, or Cypress Component Test Runner and might not be available in test runners without a browser environment like Jest or Mocha.

With dependendencies set up for our test, we call and resolve the static method RouterTestingHarness.create to create an instance of a RouterTestingHarness as demonstrated in the following code snippet.

const harness = await RouterTestingHarness.create();

We could have pass an initial URL to the method to activate the component-under-test, HeroDetailComponent but we will do that using the RouterTestingHarness#navigateByUrl method instead.

⚠️ Warning
RouterTestingHarness.create must only be called once per test case and requires ModuleTeardownOptions#destroyAfterEach to be set to true (the default value).

The RouterTestingHarness#navigateByUrl method optionally accepts the component we want to activate and asserts that this is the result of navigating to the specified application URL as seen in the following code snippet.

const component = await harness
  .navigateByUrl('superhero/12', HeroDetailComponent);

As suggested by the previous code snippet, the activated component instance is resolved by the Promise returned by the RouterTestingHarness#navigateByUrl method.

I recommend that we make test assertions via the DOM to also exercise the component template. Additionally, this avoid relying on implementation details like whether the loaded hero is represented as a raw data structure, an RxJS Observable, or an Angular Signal. This decreases the brittleness of the test to support refactoring the component and its collaborators without breaking our component test.

To make assertions via the DOM, we use either of the RouterTestingHarness#routeDebugElement or the RouterTestingHarness#routeNativeElement properties.

const heading = harness
  .routeNativeElement
  ?.querySelector('h3')
  ?.textContent
  ?.trim() ?? '';
expect(heading).toBe('Dr. Nice');

In the previous code snippet, we use the RouterTestingHarness#routeNativeElement property to access the DOM managed by Angular and HeroDetailComponent. We query for the hero heading and assert its content to be Dr. Nice, the name of the hero who has the ID of 12 as specified in the application URL we navigated to using the RouterTestingHarness#navigateByUrl method.

The final test suite looks something like this:

import { provideLocationMocks } from '@angular/common/testing';
import { TestBed } from '@angular/core/testing';
import {
  provideRouter,
  withComponentInputBinding,
} from '@angular/router';
import { RouterTestingHarness } from '@angular/router/testing';
import { HeroDetailComponent } from './hero-detail.component';

describe(HeroDetailComponent.name, () => {
  it('displays the name of the hero', async () => {
    TestBed.configureTestingModule({
      providers: [
        provideRouter([
          {
            path: 'superhero/:id',
            component: HeroDetailComponent,
          },
        ]),
        provideLocationMocks(),
      ],
    });

    const harness = await RouterTestingHarness.create();
    const component = await harness.navigateByUrl(
      'superhero/12',
      HeroDetailComponent
    );

    const heading = harness
      .routeNativeElement
      ?.querySelector('h3')
      ?.textContent
      ?.trim() ?? '';
    expect(heading).toBe('Dr. Nice');
  });
});

Great, we successfully exercised a routed Angular component in a component test! Better yet, because the test uses RouterTestingHarness and makes assertions via the DOM, it is resilient to component and service refactorings.

As an exercise, write a routed component test similar to the one in the previous code listing. Then refactor the component to accept an input property instead of depending on ActivatedRoute and provide the withComponentInputBinding Angular Router feature. The only thing you should have to change in your test is to provide the same Angular Router feature to the Angular tesitng module.

Manage Nx library dependencies with the @nx/dependency-checks ESLint rule

Lars Gyrup Brink Nielsen — Thu, 06 Jul 2023 21:56:24 +0000

Cover art by DALL-E.

Nx 16.4 introduces the @nx/dependency-checks ESLint rule to the @nx/linter package for verifying, adding, removing, and updating peerDependencies in the package.json source configuration file of buildable or publishable Nx library projects.

💡 Tip
Prefer at least Nx version 16.5 when using the @nx/dependency-checks lint rule. Significant bugs were patched in this version.

This is a replacement for the updateBuildableProjectDepsInPackageJson and buildableProjectDepsInPackageJsonType Nx build executor options so expect them to be deprecated. In fact, they are turned off by default in Nx 16.6 (but migrated to true for existing projects) and these options shouldn't be used for a project using the @nx/dependency-checks ESLint rule.

Let's start with instructions on adding the lint rule to a library project.

Enabling @nx/dependency-checks in .eslintrc.json

To enable the @nx/dependency-checks ESLint rule in a buildable or publishable library project, open its .eslintrc.json ESLint configuration file and add the following settings to the overrrides array in the file.

{
  "overrides": [
    {
      "files": ["{package,project}.json"],
      "parser": "jsonc-eslint-parser",
      "rules": {
        "@nx/dependency-checks": "error"
      }
    }
  ]
}

Excerpt of the overrides section of the project-specific .eslintrc.json file.

This enables the @nx/dependency-checks ESLint rule with default options.

ℹ️ Info
We do not have to install json-eslint-parser as a dependency in our workspace as it is a direct dependency of the @nx/eslint-plugin package, not a peer dependency.

The lint rule scans the project's package.json and project.json files. Because of this, we must also add these files to the lint file patterns in the project.json configuration file as described in the next section.

Including configuration files in the lint target

To pass the package.json and project.json files to ESLint, we must add them to the lintFilePatterns option for the @nx/linter:eslint Nx executor as seen in the following code snippet.

{
  "targets": {
    "lint": {
      "executor": "@nx/linter:eslint",
      "outputs": ["{options.outputFile}"],
      "options": {
        "lintFilePatterns": [
          "libs/ui-design-system/**/*.ts",
          "libs/ui-design-system/**/*.html",
          "libs/ui-design-system/package.json",
          "libs/ui-design-system/project.json"
        ]
      }
    }
  }
}

Excerpt of the targets section of the project.json file.

In addition to the existing lint file patterns, we add one listing the path of the project's package.json file and one listing the path of the project.json file, for example:

"libs/ui-design-system/package.json"
"libs/ui-design-system/project.json"

Configuring @nx/dependency-checks options

The @nx/dependency-checks ESLint rule supports a range of options. Let's have a look at the default settings and then explore them all.

To match the default ESLint rule options, we add the following to the library project's .eslintrc.json ESLint configuration file.

{
  "overrides": [
    {
      "files": ["{package,project}.json"],
      "parser": "jsonc-eslint-parser",
      "rules": {
        "@nx/dependency-checks": [
          "error",
          {
            "buildTargets": ["build"],
            "checkMissingDependencies": true,
            "checkObsoleteDependencies": true,
            "checkVersionMismatches": true,
            "ignoredDependencies": []
          }
        ]
      }
    }
  ]
}

Excerpt of the overrides section of the project-specific .eslintrc.json file.

The buildTargets option

We use buildTargets to instruct the lint rule about the Nx target(s) that we use to build the library. This is used to determine the library's dependencies.

The checkMissingDependencies option

This lint check determines the library's dependencies from its source code and compares it to the dependencies and peer dependencies listed in its package.json file.

As an example, we add the following Button Angular component to a library.

import { Component } from '@angular/core';
import { MatButtonModule } from '@angular/material/button';

@Component({
  standalone: true,
  selector: 'myorg-button',
  imports: [MatButtonModule],
  template: `<button mat-button><ng-content /></button>`,
})
export class MyOrgButtonComponent {}

If we don't add @angular/material and its peer dependency @angular/cdk to the library's package.json file, we get lint errors like the following.

libs\ui-design-system\package.json
  4:3  error  The "ui-design-system" uses the package "@angular/material", but it is missing from the project's "package.json"  @nx/dependency-checks
  4:3  error  The "ui-design-system" uses the package "@angular/cdk", but it is missing from the project's "package.json"  @nx/dependency-checks

Example lint error output when the checkMissingDependencies option is enabled.

As long as our library doesnot directly depend on @angular/cdk, we can choose to ignore the detected @angular/cdk peer dependency as installing the @angular/material package should prompt consumers to install @angular/cdk as well. See how to ignore a detected dependency in the the section The ignoredDependencies list.

The checkObsoleteDependencies option

Enable the checkObsoleteDependencies option to detect dependencies that are listed in the library's package.json file but are unused by its source code.

As an example, our MyOrgButtonComponent doesn't depend on @angular/common but it was added to the peerDependencies array of the library's package.json file by the @nx/angular:library generator. Since it is no longer a dependency, we get a lint error like the following.

libs\ui-design-system\package.json
  7:5  error  The "@angular/common" package is not used by "ui-design-system"  @nx/dependency-checks

Example lint error output when the checkObsoleteDependencies option is enabled.

On the other hand, we want to keep tslib in the dependencies section of the Angular library's package.json file so we must add it to the ´ignoredDependencies´ list as described in the The ignoredDependencies list section.

The checkVersionMismatches option

The lint check enabled when the value of the checkVersionMismatches option is set to true verifies that the version range listed in the library's package.json file includes the version installed in the Nx workspace.

As an example, our Nx workspace uses Angular with the following version range listed in the dependencies array of the package.json file in the root of the workspace.

{
  "dependencies": {
    "@angular/core": "~16.1.0",
  }
}

Excerpt of the dependencies section of the workspace-level package.json file.

The package.json file of our example Angular library has the following version range for @angular/core.

{
  "peerDependencies": {
    "@angular/core": "^15.1.0"
  }
}

Excerpt of the peerDependencies section of the project's package.json file.

When we lint the library, we get a lint error like the following.

libs\ui-design-system\package.json
  6:5  error  The version specifier does not contain the installed version of "@angular/core" package: 16.1.3  @nx/dependency-checks

Example lint error output when the checkVersionMismatches option is enabled.

The ignoredDependencies list

To exclude certain packages from the dependency checks, we add them to the ignoredDependencies array. This option does not support glob patterns.

For example, when we generate an Angular library, the Angular-specific classes use the @angular/core package which has a peer dependency on zone.js and rxjs. As long as our library don't have direct dependencies on these packages, we can choose to add them to the ignoredDependencies list as seen in the following code snippet.

{
  "overrides": [
    {
      "files": ["{package,project}.json"],
      "parser": "jsonc-eslint-parser",
      "rules": {
        "@nx/dependency-checks": [
          "error",
          {
            "buildTargets": ["build"],
            "checkMissingDependencies": true,
            "checkObsoleteDependencies": true,
            "checkVersionMismatches": true,
            "ignoredDependencies": [
              "rxjs",
              "zone.js"
            ]
          }
        ]
      }
    }
  ]
}

Excerpt of the overrides section of the project-specific .eslintrc.json file.

In the section The checkObsoleteDependencies option, we said that we want to keep tslib in the dependencies section of the Angular library's package.json file. To do so, we must add it to the ignoredDependencies list as seen in the following code snippet.

{
  "overrides": [
    {
      "files": ["{package,project}.json"],
      "parser": "jsonc-eslint-parser",
      "rules": {
        "@nx/dependency-checks": [
          "error",
          {
            "buildTargets": ["build"],
            "checkMissingDependencies": true,
            "checkObsoleteDependencies": true,
            "checkVersionMismatches": true,
            "ignoredDependencies": [
              "rxjs",
              "tslib",
              "zone.js"
            ]
          }
        ]
      }
    }
  ]
}

Excerpt of the overrides section of the project-specific .eslintrc.json file.

As described in the section The checkMissingDependencies option, we can choose to ignore the @angular/cdk peer dependency as well as long as our library has no direct dependency on @angular/cdk. Let's add it to the ignoredDependencies, keeping in mind that if we add an import statement targeting @angular/cdk, we must remove this package from the ignoredDependencies list again.

{
  "overrides": [
    {
      "files": ["{package,project}.json"],
      "parser": "jsonc-eslint-parser",
      "rules": {
        "@nx/dependency-checks": [
          "error",
          {
            "buildTargets": ["build"],
            "checkMissingDependencies": true,
            "checkObsoleteDependencies": true,
            "checkVersionMismatches": true,
            "ignoredDependencies": [
              "@angular/cdk",
              "rxjs",
              "tslib",
              "zone.js"
            ]
          }
        ]
      }
    }
  ]
}

Excerpt of the overrides section of the project-specific .eslintrc.json file.

@nx/dependency-checks lint fixers

Lint fixers are available for the following @nx/dependency-checks ESLint rule options.

checkMissingDependencies
checkObsoleteDependencies
checkVersionMismatches

ℹ️ Info
The lint fixers for the checkMissingDependencies and checkVersionMismatches lint checks insert or replace version ranges in the Nx library's package.json file with the ones listed in the Nx workspace's root-level package.json file. This usually works well with buildable libraries but make sure to verify version ranges for publishable libraries.

The lint fixer for the checkMissingDependencies ESLint rule option adds dependencies to the peerDependencies or dependencies section of the library's package.json file, depending on which section is declared first.

Ignoring test-setup.ts and similar files

The @nx/dependency-checks ESLint rule detects dependencies in files like test-setup.ts that are in the sourceRoot of a project. When using create-nx-workspace version 16.5 or newer, the solution for this is already set up for us. In existing Nx workspaces, we either run the add-test-setup-to-inputs-ignore Nx migration from the @nx/jest package or manually add the pattern "!{projectRoot}/src/test-setup.[jt]s" to nx.json#namedInputs.production as seen in the following code snippet.

{
  "namedInputs": {
    "production": [
      "default",
      "!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)?(.snap)",
      "!{projectRoot}/tsconfig.spec.json",
      "!{projectRoot}/jest.config.[jt]s",
      "!{projectRoot}/src/test-setup.[jt]s",
      "!{projectRoot}/.eslintrc.json"
    ]
  }
}

Excerpt of the namedInputs section of the nx.json file.

As you can see in the previous code snippet, jest.config.js and jest.config.ts are also ignored.

Conclusion

The @nx/dependency-checks ESLint rule introduced to the @nx/linter package in version 16.4 is an invaluable tool in managing peer dependencies of a buildable or publishable Nx library.

Its built-in lint fixers is a semi-automated way of resolving peer dependency issues in the package.json source configuration file of a library. Library dependencies are detected based on the library's source code.

This ESLint rule is a replacement for the updateBuildableProjectDepsInPackageJson and buildableProjectDepsInPackageJsonType Nx build executor options.

Stop using the defaultProject Nx CLI setting and start using NX_DEFAULT_PROJECT

Lars Gyrup Brink Nielsen — Tue, 30 May 2023 06:26:51 +0000

Cover image by DALL-E.

The defaultProject setting for the Nx CLI was originally inherited from the Angular CLI. In integrated and standalone Nx workspaces, the defaultProject setting is located in nx.json. In package-based Nx workspaces, defaultProject is located in package.json#nx. While it was removed from Angular CLI version 16, it is still present but unofficially deprecated in Nx version 16.x as evident by the nx.json reference which doesn't list it.

As of Nx 16.2, a defaultProject setting is still configured when using create-nx-workspace to generate a standalone Nx workspace. However, it is safe to remove this setting as Nx detects the project.json file in the root directory of a standalone workspace.

In this article, we discuss why the defaultProject is being deprecated, which use cases it affects with example commands not depending on it, and finally the viable replacement for defaultProject.

Why will `defaultProject` be removed?

The defaultProject setting is being depreacted and eventually removed because it doesn't make sense in integrated and package-based Nx workspaces where the preferred project usually varies between teams and developers and so shouldn't be committed to a configuration shared between most or all teams and developers.

Standalone Nx workspaces can have more than one project but the original project is defined in a package.json or project.json file in the root workspace directory which Nx detects to infer the project for Nx CLI commands run from this directory.

What does `defaultProject` affect?

Let's explore most of the use cases affected by the defaultProject setting and how we can complete them without this setting.

Running tasks

An Nx workspace defines projects, targets, and, optionally, configurations.

To run a task for a specific configuration of a project target, we use the following command format.

nx run <project>:<target>[:<configuration>]

nx run <project>:<target> [--configuration=<configuration>]

For example, to start a task running the build target on the my-app project, we use the following command.

nx run my-app:build

Common target names have alias commands, for example the following command is an alias of the previous nx run command.

nx build my-app

To make sure we use the production build configuration, we prepend :production to our nx run command as seen in the following.

nx run my-app:build:configuration

The aliased version is as follows.

nx build my-app --configuration=production

Running generators

Some Nx generators and Angular schematics require a --project option but use the defaultProject setting when omitted, for example @nx/component and @schematics/angular:component.

Without a deafultProject setting, we must pass a --project option as seen in the following example.

nx generate @nx/angular:component button --standalone --project=my-app

What should I use instead of `defaultProject`?

Although the preferred project isn't the same for all teams or developers, it is still convenient to leave out the same project name for most task runs and generators.

As a viable replacement for the defaultProject setting, we can use the NX_DEFAULT_PROJECT environment variable which is planned to outlive the defaultProject setting as we have many options for setting this in individual environments, both for CI and local development use cases.

When we set the value of the NX_DEFAULT_PROJECT environment variable to a project name, both task running and code generation works as if we had specified the defaultProject setting but without committing it to a shared configuration.

For example, with the NX_DEFAULT_PROJECT environment variable set to my-app, we can use the following build commands.

# build the app
nx run build
# or
nx build

# build the app in production mode
nx run build:production
# or
nx build --configuration=production

Additionally, we can use generators and schematics that require a --project option witout specifying a project.

nx generate @nx/angular:component button --standalone
# or
nx generate @schematics/angular:component button --standalone

Conclusion

In this article, we learned that defaultProject is being deprecated and removed because it is no longer necessary for standalone Nx workspaces and in the case of integrated or package-based Nx workspaces, different teams and developers often want a different default project. Because of this, we shouldn't commit a shared setting.

We learned how the defaultProject setting affects the nx run command as well as Nx generators and Angular schematics that require a --project option.

Finally, we learned how we can use the NX_DEFAULT_PROJECT environment variable to configure an individual environment for CI tasks or local development in the same way as we would have used the defaultProject setting in the past but without committing a setting to a shared configuration.

Testing Angular routing components with RouterTestingHarness, provideLocationMocks, and provideRouter

Lars Gyrup Brink Nielsen — Wed, 08 Feb 2023 23:54:59 +0000

Cover art by DALL·E 2.

It's been three years since Testing Angular routing components with the RouterTestingModule. This article revisits integrated routing component tests with modern Angular APIs, including standalone components, provideRouter, provideLocationMocks, and RouterTestingHarness. Additionally, we use a SIFERS for managing our test setup and test utilities.

The show hero detail use case.

providerRouter and provideLocationMocks

provideRouter (introduced by Angular version 14.2) is the standalone version of RouterModule.forRoot. Combine it with provideLocationMocks (introduced by Angular version 15.0) and we have the standalone version of RouterTestingModule.withRoutes.

ℹ️ Note
Read What does the RouterTestingModule do? for a detailed explanation of how RouterTestingModule replaces Angular Router dependencies. provideLocationMocks does the same.

RouterTestingHarness

RouterTestingHarness (introduced by Angular version 15.2) is similar to Spectacular's Feature testing API.

When we call RouterTestingHarness.create (only call it once per test), a test root component with a router outlet is created behind the scenes but we don't get access to this component or its component fixture.

The resolved RouterTestingHarness instance has the properties routeDebugElement and routeNativeElement which access the DebugElement and HTMLElement corresponding to the component currently activated by the test root component's RouterOutlet.

RouterTestingHarness has a detectChanges method which calls ComponentFixture#detectChanges for the test root component.

The RouterTestingHarness#navigateByUrl method wraps Router#navigateByUrl and resolves the component activated by that navigation.

That's all the background we need. Let's explore a RouterTestingHarness version of the integrated routed component test for the DashboardComponent from the Tour of Heroes Router tutorial.

Integrated routing component test suite

import { Location } from '@angular/common';
import { provideLocationMocks } from '@angular/common/testing';
import { Component } from '@angular/core';
import {
  fakeAsync,
  TestBed,
  tick,
} from '@angular/core/testing';
import { By } from '@angular/platform-browser';
import { provideRouter } from '@angular/router';
import { RouterTestingHarness } from '@angular/router/testing';
import { asapScheduler, of } from 'rxjs';
import { observeOn } from 'rxjs/operators';

import { HeroService } from '../hero.service';
import { HEROES } from '../mock-heroes';
import { DashboardComponent } from './dashboard.component';

async function setup() {
  const fakeService = {
    getHeroes() {
      return of([...HEROES]).pipe(observeOn(asapScheduler));
    },
  } as Partial<HeroService>;

  TestBed.configureTestingModule({
    providers: [
      provideRouter([
        {
          path: '',
          pathMatch: 'full',
          component: DashboardComponent,
        },
        {
          path: 'detail/:id',
          component: TestHeroDetailComponent,
        },
      ]),
      provideLocationMocks(),
      { provide: HeroService, useValue: fakeService },
    ],
  });

  const harness = await RouterTestingHarness.create(); // [1]
  const location = TestBed.inject(Location);

  return {
    advance() {
      tick();
      harness.detectChanges();
    },
    clickTopHero() {
      const firstHeroLink = harness.routeDebugElement.query(
        By.css('a')
      );

      firstHeroLink.triggerEventHandler('click', {
        button: leftMouseButton,
      });
    },
    harness,
    location,
  };
}

@Component({
  standalone: true,
  template: '',
})
class TestHeroDetailComponent {}

const leftMouseButton = 0;

describe('DashboardComponent (integrated)', () => {
  it('navigates to the detail view when a hero link is clicked', fakeAsync(async () => {
    const { advance, clickTopHero, harness, location } =
      await setup();
    const component /* [2] */ = await harness.navigateByUrl(
      '/',
      DashboardComponent // [3]
    );
    const [topHero] = component.heroes;

    clickTopHero();
    advance();

    const expectedPath = '/detail/' + topHero.id;
    expect(location.path())
      .withContext(
        'must navigate to the detail view for the top hero'
      )
      .toBe(expectedPath);
  }));
});

(1) Notice how we only call RouterTestingHarness.create once per test case in our setup SIFERS.

⚠️ Warning
ModuleTeardownOptions#destroyAfterEach must be set to true for RouterTestingHarness to work correctly. See Improving Angular tests by enabling Angular testing module teardown for details on this option.

(1) We could have passed an initial URL, for example await RouterTestingHarness.create("/") or await RouterTestingHarness.create("/heroes") but it doesn't return an activated component.

(2) RouterTestingHarness#navigateByUrl resolves an activated component and optionally accepts the type (class) of the activated component we expect (3). If the component activated by that navigation is not of the expected type, an error is thrown.

The full test suite is available in this Gist.

Summary

Let's sum up what we learned in this article:

RouterTestingHarness (introduced by Angular version 15.2) is a testing harness specifically for interacting with Angular Router-related APIs in tests
provideRouter (introduced by Angular version 14.2) is the standalone version of RouterModule.forRoot.
provideLocationMocks (introduced by Angular version 15.0) is the standalone version of RouterTestingModule
The standalone version of RouterTestingModule.withRoutes is provideRouter and provideLocationMocks combined.

RouterTestingHarness.create creates an initializes a test root component with a router outlet. It must only be called once per test case and requires ModuleTeardownOptions#destroyAfterEach to be set to true. It optionally accepts an initial URL.

RouterTestingHarness#navigateByUrl accepts a URL for navigation and optionally the expected type of the component activated by that navigation. The activated component is resolved by the method call.

RouterTestingHarness#detectChanges triggers a change detection cycle starting at the test root component.

YAML collections: Sequences and mappings

Lars Gyrup Brink Nielsen — Mon, 21 Nov 2022 17:14:55 +0000

Cover photo by Karen Vardazaryan on Unsplash.

Sequences

A sequence is a YAML node that contains an ordered list of zero to n YAML nodes (mappings, sequences, or scalars). Sequences are commonly known as arrays or lists in other languages.

Block collection style

A block sequence is a series of YAML nodes lead by a dash (-) indicator and white space.

integers:
  - 1
  - 2
  - 3
  - 4
  - 5
  - 6
  - 7
  - 8
  - 9
  - 10
colors:
  - red
  - green
  - blue
  - yellow
  - cyan
  - magenta
  - black
  - white

In JSON, this is

{
  "integers": [
    1,
    2,
    3,
    4,
    5,
    6,
    7,
    8,
    9,
    10
  ],
  "colors": [
    "red",
    "green",
    "blue",
    "yellow",
    "cyan",
    "magenta",
    "black",
    "white"
  ]
}

Flow collection style

A flow sequence is a series of YAML nodes contained in square brackets ([ and ]). Flow sequence entries are separated by a comma (,) with a trailing comma allowed but empty node entries disallowed.

integers: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
colors: [red, green, blue, yellow, cyan, magenta, black, white]

but also

integers: [
  1, 2,
3, 4, 5,
  6, 7, 8, 9,
10,
]
colors: [red, green, blue,
yellow, cyan, magenta, black, white]

or any other white space variation.

In JSON, this is

{
  "integers": [
    1,
    2,
    3,
    4,
    5,
    6,
    7,
    8,
    9,
    10
  ],
  "colors": [
    "red",
    "green",
    "blue",
    "yellow",
    "cyan",
    "magenta",
    "black",
    "white"
  ]
}

Mappings

A mapping is a YAML node that contains an unordered set of zero to n key-value pairs. A key and its value are separated by a colon (:). Keys must be unique. Both keys and values may be any kind of YAML node. Mappings are commonly known as hash maps or associative arrays in other languages.

Block collection style

A block mapping is a series of key-value pairs on separate lines.

integer: 3
color: blue

In JSON, this is

{
  "integer": 3,
  "color": "blue"
}

Flow collection style

A flow mapping is a series of key-value pairs contained in curly braces ({ and }). Flow mapping entries are separated by a comma (,) with a trailing comma allowed but empty node entries disallowed.

{ integer: 3, color: blue }

but also

{
  integer: 3,
color: blue,}

or any other white space variation.

In JSON, this is

{
  "integer": 3,
  "color": "blue"
}

Explicit mapping entries

A mapping key and value pair is optionally put on separate lines where the key is lead by a question mark (?) and the value is lead by a colon (:). This allows for special keys such as the empty node or complex non-scalar nodes.

? 
: My key is empty
? - 3
  - [blue]
  - { autocorrect: On }
: My key is a nested collection

The previous example is a mapping containing two key-value pairs where the values are strings. It has no equivalent JSON expression.

The local component scope of standalone Angular components

Lars Gyrup Brink Nielsen — Wed, 31 Aug 2022 07:03:12 +0000

Cover photo by Clay Banks on Unsplash.

A standalone component is independent from an Angular module. It directly references the declarables (components, directives, and pipes) used in its template.

Declarable dependencies

A standalone Angular component specifies declarable dependencies in the Component.imports metadata option to manage its local component scope.

Let's consider a standalone implementation of the hero detail component from the Tour of Heroes tutorial:

import { NgIf, UpperCasePipe } from '@angular/common';
import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';

@Component({
  imports: [FormsModule, NgIf, UpperCasePipe],
  selector: 'toh-hero-detail',
  standalone: true,
  styleUrls: ['./hero-detail.component.css'],
  template: `
    <div *ngIf="hero">
      <h2>{{ hero.name | uppercase }} Details</h2>
      <div><span>id: </span>{{ hero.id }}</div>
      <div>
        <label for="hero-name">Hero name: </label>
        <input
          id="hero-name"
          [(ngModel)]="hero.name"
          placeholder="Hero name"
        />
      </div>
      <button type="button" (click)="goBack()">go back</button>
      <button type="button" (click)="save()">save</button>
    </div>
  `,
})
export class HeroDetailComponent {
  // Class body omitted
}

Importantly, the Component.standalone metadata option is set to true.

Next, we list declarable dependencies and/or Angular modules exporting declarbales in the Component.imports metadata option. See how the structural directive NgIf is listed alongside the Angular pipe UppercasePipe, both from the @angular/common package. This is possible since they are both standalone declarables in modern versions of Angular.

ℹ️ Note
It is still possible to import CommonModule to introduce all the common Angular declarables to a standalone component's local component scope.

Additionally, the FormsModule is added to the Component.imports metadata option, introducing the attribute directive NgModel to the hero detail component's local component scope.

ℹ️ Note
Importantly, components, directives, and pipes listed in Component.imports must be marked with the standalone: true metadata option available as Component.standalone, Directive.standalone, and Pipe.standalone.

The default setting for this metadata option is standalone: false as of Angular version 15, subject to future change depending on how well standalone declarables are received by the Angular ecosystem and community.

Inspecting the component template, we see the NgIf directive in use:

<div *ngIf="hero">
  <!-- Conditional content omitted -->
</div>

Next, we see the UppercasePipe pipe being used in the template:

<h2>{{ hero.name | uppercase }} Details</h2>

Finally, the Hero#name property is bound to a form control using two-way data binding with the NgModel directive:

<input
  id="hero-name"
  [(ngModel)]="hero.name"
  placeholder="Hero name"
/>

Local component scope

In the dependency graph of the standalone hero detail component's local component scope, we see the relationship between our component and its declarable dependencies:

With the exception of the FormsModule, this closely matches the component template's indirect dependencies on declarables it uses:

Indirect dependencies meaning that the component template uses the element selectors, attribute selectors, and pipe names specified in the Component.selector, Directive.selector, and Pipe.name metadata options of the component's declarable dependencies.

Transitive compilation scope

When we compare this to the transitive compilation scope of the declaring module of a classic Angular component, we notice an increased mental overhead in the classic Angular component style:

The HeroDetailModule and CommonModule introduce layers of indirection to the dependency graph. Instead of a direct dependency from the HeroDetailComponent to NgIf and UppercasePipe, there is no direct flow of dependencies between the HeroDetailComponent class and any of its declarable dependencies. This is caused by the HeroDetailModule referencing the HeroDetailComponent, not the other way around. Another indirection is the unnecessary CommonModule encapsulating the Angular declarables of which we only use 2 in the component template.

The classic Angular dependency graph does not match the component template's indirect dependencies on declarables it needs.

Imagine the logic needed by the Angular compiler to determine dependencies between classes and the maintenance it requires when significant changes are made to Angular, the TypeScript compiler, and other dependencies.

What's worse, the previous classic dependency graph is simplified. The full transitive compilation scope of the hero detail module is seen in this expanded classic dependency graph:

That's 52 declarables imported to the transitive compilation scope of which the component template uses only 3. Fifty-two.

Luckily for us, the Angular Development Kit's Build Optimizer tree shakes unused declarables from transitive compilation scopes and local component scopes. If that was not the case, our bundle would increase every time we imported an Angular module that exported more declarables than we were using in our component template.

This brings us to the next topic: Maintenance.

Maintaining declarable dependencies

Take another look at the previous expanded transitive compilation scope. As the codebase evolves, how do we keep the declarable dependencies in sync with the transitive compilation scope? How do we determine when our component template no longer uses any declarable from an Angular module exporting more than a dozen declarables.

This gets harder for every declared component in an Angular module and every non-SCAM module imported.

ℹ️ Note
It's time to convert SCAMs to standalone declarables. That was always their purpose, after all.

It's easier to scan a standalone component template and compare it to the imported standalone declarables listed in the Component.imports metadata option.

Conclusion

A standalone component has a local component scope consisting of its declarables dependencies which are listed in the Component.imports metadata option.

We must maintain the local component scope so that it matches the declarables used in the component template. We do this by comparing the standalone component template to the standalone declarables and Angular modules listed in the Component.imports metadata option, keeping them in sync.

Common declarables such as NgIf and UppercasePipe that are exported by CommonModule are now standalone declarables that can be referenced directly in the Component.imports metadata option.

Angular Revisited: Standalone Angular applications, the replacement for NgModules

Lars Gyrup Brink Nielsen — Tue, 30 Aug 2022 14:00:17 +0000

Cover photo by Laura Cleffman on Unsplash.

It's been 4 years since I started looking into standalone Angular applications, that is Angular applications that unlike classic Angular applications have no Angular modules.

Angular version 15 delivers an amazing full-on standalone Angular application experience and it is about much more than standalone components. It is a shift in perspective on Angular concepts as we know them.

Optional NgModules

Standalone Angular applications mark the final milestone of the optional NgModules epic. No longer do we have to use or write Angular modules. We now have an alternative for every use case.

Angular modules are one of the most confusing concepts of the Angular framework. The vision for Angular was to get rid of Angular modules following AngularJS versions 1.x but shortly before Angular version 2.0, Angular modules were reintroduced for the sake of the compiler to pave the path for application-scoped Ahead-of-Time compilation, a major improvement compared to Just-in-Time compilation, the only compilation mode for AngularJS.

Angular modules are difficult to teach and learn. Introduced as necessary compiler annotations rather than to improve the developer experience, Angular modules address many concerns with declarable linking to component templates and environment injector configuration being the two major concerns.

@NgModule({
  bootstrap: [AppComponent],
  declarations: [AppComponent],
  entryComponents: [AppComponent],
  exports: [AppComponent],
  id: 'app',
  imports: [
    BrowserAnimationsModule,
    HttpClientModule,
    CommonModule,
    MatButtonModule,
    RouterModule.forRoot(routes),
  ],
  jit: false,
  providers: [AppService],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

Let's have a look at every metadata option for the NgModule decorator, discuss their purpose and their standalone application replacements.

NgModule.bootstrap

Marks one or more components to be bootstrapped as root components.

Replace with bootstrapApplication.

NgModule.declarations

Declares components, directives, and pipes, including them in Angular module's transitive compilation scope.

⚠️ Warning
A classic component, directive, or pipe can only be declared in one Angular module. Declaring them in multiple Angular modules results in compilation errors.

Replace with the Component.imports, Component.standalone, Directive.standalone, and Pipe.standalone metadata options.

NgModule.entryComponents

Deprecated since Angular version 9, the first stable release of Angular Ivy, the NgModule.entryComponents option marks a component for dynamic rendering support. This was implicitly done for components marked with NgModule.bootstrap and Route#component in the Angular Template Compiler and Angular View Engine framework generations.

ℹ️ Note
Stop using this metadata option in classic Angular applications.

In Angular Ivy, components do not have to be marked explicitly as entry components. Dynamic rendering of any component is possible so no replacement is necessary.

NgModule.exports

Marks classic and/or standalone declarables as part of this Angular module's transitive exported scope. Listing other Angular modules includes their transitive exported scope in this Angular module's transitive exported scope.

Replace with the native export declaration to make a standalone declarable accessible to the template of a component including it in its Component.imports metadata option or the transitive scope of an Angular module including it in its NgModule.imports or NgModule.exports metadata options.

To indicate public or internal access to a standalone declarable, we can structure our Angular workspaces using barrel files, workspace libraries, and or lint rules.

NgModule.id

Marks this Angular module as non-tree-shakable and allows access through the getNgModuleById function.

⚠️ Warning
You probably don't need this option.

Not needed in standalone applications. For classic application, replace with a dynamic import statement, for example:

const TheModule = await import('./the.module')
  .then(esModule => esModule.TheModule);

NgModule.jit

Excludes this Angular module and its declarations from Ahead-of-Time compilation.

ℹ️ Note
The JIT compiler must be bundled with the application for this option to work for example by adding the following statement in the main.ts file:
import '@angular/compiler';

Introduced in Angular version 6 to support the ongoing work of what was going to be the next framework generation, Angular Ivy.

Replace with the Component.jit and Directive.jit metadata options.

NgModule.imports

Includes the transitive exported scope of listed Angular modules in this Angular module's transitive module scope. Standalone declarables can also be listed to include them in this Angular module's transitive module scope.

This links imported declarables to templates of components declared by this Angular module.

Providers listed in Angular modules added to the NgModule.imports metadata option are added to the environment injector(s) (formerly known as module injectors) that this Angular module is part of.

To mark components, directives, and pipes as declarable dependencies of a standalone component, use its Component.imports metadata option which also supports Angular modules.

NgModule.providers

Lists providers that are added to the environment injector(s) (formerly known as module injectors) that this Angular module is part of.

Angular version 6 introduced tree-shakable providers, removing the need for Angular modules to configure environment injectors, at the time known as module injectors.

Replace NgModule.providers with the InjectionToken.factory metadata option, Injectable.providedIn metadata option, Route#providers setting, and ApplicationConfig#providers setting.

💡 Tip
Consider using a component-level provider to follow the lifecycle of a directive or component by specifying the Component.providers, Component.viewProviders, and Directive.providers metadata options. Consider this both for classic and standalone Angular applications.

NgModule.schemas

Adds template compilation schemas to support web component usage by listing the CUSTOM_ELEMENTS_SCHEMA or to ignore the use of any unknown element, attribute, or property by listing the NO_ERRORS_SCHEMA.

This controls the template compilation schemas for components that are declared by this Angular module.

Replace with the Component.schemas metadata option.

As we have learned in this introductory article, every possible Angular module metadata option now has a standalone Angular application replacement.

Standalone alternatives for official Angular modules

Several Angular modules are exposed in the public APIs of official Angular packages. As of Angular version 15.1, there are standalone alternatives for the following official Angular modules:

Angular module	Standalone replacement
`BrowserAnimationsModule`	`provideAnimations`
`CommonModule`	`AsyncPipe`, `CurrencyPipe`, `DatePipe`, `DecimalPipe`, `I18nPluralPipe`, `I18nSelectPipe`, `JsonPipe`, `KeyValuePipe`, `LowerCasePipe`, `NgClass`, `NgComponentOutlet`, `NgIf`, `NgForOf`, `NgPlural`, `NgPluralCase`, `NgStyle`, `NgSwitch`, `NgSwitchCase`, `NgSwitchDefault`, `NgTemplateOutlet`, `PercentPipe`, `SlicePipe`, `TitleCasePipe`, and `UppercasePipe`
`CdkScrollableModule`	`CdkScrollable`
`DragDropModule`	`CdkDrag`, `CdkDragHandle`, `CdkDragPlaceholder`, `CdkDragPreview`, `CdkDropList`, `CdkDropListGroup`, and `CdkScrollable`
`HttpClientModule`	`provideHttpClient`
`HttpClientJsonpModule`	`provideHttpClient` and `withJsonpSupport`
`HttpClientTestingModule`	`provideHttpClientTesting`
`HttpClientXsrfModule`	`provideHttpClient`, `withNoXsrfProtection` and `withXsrfConfiguration`
`NoopAnimationsModule`	`provideNoopAnimations`
`RouterModule`	`provideRouter`, `RouterLink`, `RouterLinkActive`, `RouterOutlet`, `withDebugTracing`, `withDisabledInitialNavigation`, `withEnabledBlockingInitialNavigation`, `withHashLocation`, `withInMemoryScrolling`, `withPreloading`, and `withRouterConfig`
`ScrollingModule`	`CdkFixedSizeVirtualScroll`, `CdkScrollable`, `CdkVirtualForOf`, `CdkVirtualScrollableElement`, `CdkVirtualScrollableWindow`, and `CdkVirtualScrollViewport`

ℹ️ Note
The classic Angular modules can still be used and are not deprecated.

Standalone vs. classic Angular applications

Due to interoperability between standalone APIs and Angular modules, standalone Angular applications do not require a big bang migration. We can gradually migrate to standalone APIs or use standalone APIs for new features but leave the classic Angular APIs in-place for now.

In Angular version 15.x, picking between standalone and classic Angular applications was mostly a stylistic choice. However, there are already noteworthy differences to consider:

bootstrapApplication and createApplication do not support NgZone options unlike PlatformRef#bootstrapModule, making it impossible to exclude Zone.js from our standalone application bundle using these APIs
The Directive composition API only supports standalone directives and components as host directives
Standalone APIs are easier to teach and learn because of less mental overhead and simpler APIs using native data structures without framework-specific metadata
The Angular Language Service only supports automatic imports for standalone components
Component testing is easier with standalone declarables
Storybook stories are easier with standalone declarables
Standalone components can be lazy-loaded and dynamically rendered using ViewContainerRef#createComponent
Standalone components can be wrapped in React components as demonstrated by the ngx-reactify proof-of-concept Gist
Standalone components can be rendered and hydrated by Astro by using a plugin by Analog.js
@defer blocks only support standalone components in their derrable views

You take the blue pill, the story ends, you wake up in your bed and believe whatever you want to believe. You take the red pill, you stay in wonderland, and I show you how deep the rabbit hole goes.
—Morpheus

Angular CLI example for Jest Preview - the visual debugger for Jest

Lars Gyrup Brink Nielsen — Mon, 22 Aug 2022 11:22:31 +0000

Recently, I contributed an Angular CLI example for Jest Preview in collaboration with its creator, Hung Viet Nguyen.

Jest Preview

Jest Preview is a visual debugger for Jest component tests. It runs a preview server and either displays the rendered DOM of a failed test when the autoPreview option is set or the test we explicitly mark for debugging using the debug function, for example:

// counter.component.spec.ts
import { render, screen } from '@testing-library/angular';
import userEvent from '@testing-library/user-event';
import preview from 'jest-preview';
import { CounterComponent } from './counter.component';
import './counter.component.css'; 

describe(CounterComponent.name, () => {
  it('initially has a zero count', async () => {
    const user = userEvent.setup();
    await render(CounterComponent);

    // Open http://localhost:3336 to see preview
    // Require to run `jest-preview` server before
    preview.debug(); // 👈

    expect(await screen.findByTestId('count')).toContainHTML('0');
  });
});

Angular CLI integration

The Angular CLI guide for Jest Preview refers to the common installation and usage instructions while describing Angular-specific configuration and usage instructions.

While there is room for improvement, we documented workarounds in the guide. Jest Preview is not currently able to automatically transform styleUrls in component tests, support inline component styles, or automatically import application-wide stylesheets. Because of this, we have to add stylesheet import statements in our tests to match the external stylesheet used by the component-under-test.

For example, say we have this counter component:

// counter.component.ts
import { Component } from '@angular/core';

@Component({
  selector: 'app-counter',
  standalone: true,
  styleUrls: ['./counter.component.css'], // 👈
  template: `
    <button type="button" (click)="onCount()">
      The count is:
      <div data-testid="count">{{ count }}</div>
    </button>
  `,
})
export class CounterComponent {
  count = 0;

  onCount(): void {
    this.count += 1;
  }
}

We would have to add an import statement for ./counter.component.css in our component test:

// counter.component.spec.ts
import { render, screen } from '@testing-library/angular';
import userEvent from '@testing-library/user-event';
import preview from 'jest-preview';
import { CounterComponent } from './counter.component';
import './counter.component.css'; // 👈

describe(CounterComponent.name, () => {
  it('displays multiple counts', async () => {
    const user = userEvent.setup();
    await render(CounterComponent);

    await user.click(await screen.findByRole('button'));
    await user.click(await screen.findByRole('button'));

    // Open http://localhost:3336 to see preview
    // Require to run `jest-preview` server before
    preview.debug();

    expect(await screen.findByTestId('count')).toContainHTML('2');
  });
});

Docusaurus website for Analog.js - the full-stack meta-framework for Angular using Vite

Lars Gyrup Brink Nielsen — Sun, 21 Aug 2022 19:28:06 +0000

Brandon Roberts is creating the first full-stack meta-framework for Angular and it is open sourced under the MIT license.

Recently, I contributed:

A website with documentation using Docusaurus, GitHub Pages, and GitHub Actions
Cypress end-to-end test suites demonstrating and verifying how to use Cypress with Vite as the development server for an Angular application

The analogjs.org website

The official website for Analog.js is analogjs.org. I set it up using Docusaurus on a free GitHub Pages host with the brand-new GitHub Pages experience using GitHub Actions[blog post][documentation], GitHub Environments, and GitHub Deployments.

I created this video demonstrating how to set up a Docusaurus website from scratch using GitHub Pages and GitHub Actions.

The home page

The hero banner on the home page links to the documentation and an Analog.js sandbox on StackBlitz.

Next, the home page lists the current and upcoming features of Analog.js:

Vite-powered
Hybrid SSR/SSG-support
File-based routing
API (server) routes

While the Angular CLI has been using Webpack for a number of years, more modern and especially faster alternatives have emerged in the web ecosystem. One of them is Vite. Analog.js publishes an Angular plugin for Vite demonstrating:

A Vite development server
Bundling an application using Vite
Unit testing using Vitest
End-to-end-testing using a Vite development server

Documentation

Navigating to the documentation, the initial version of the website has these pages:

Introduction
Installation
Contributors
Contributing
Sponsoring

Packages

Currently, two npm packages are released and documented:

The first package is a Vite plugin to support Angular applications and the initializer scaffolds an Analog project.

End-to-end testing using Cypress and Vite

Cypress is a popular end-to-end testing framework. When using the Angular CLI, Webpack is used as the development server for Angular applications. The Analog.js repository covers the Angular Getting Started tutorial application with end-to-end tests using Cypress with the Vite development server.

More to come

Analog.js is just getting started. There are plenty of areas to contribute in. Contribute to Analog.js' GitHub issues or support the core team on GitHub Sponsors to help make it happen.

Spectacular prerelease v0.5 supports standalone feature tests and uses partial Ivy compilation

Lars Gyrup Brink Nielsen — Wed, 10 Aug 2022 18:53:38 +0000

Cover art by DALL-E.

In July 2022, we published the version 0.5.0 of Spectacular, the integration testing library for Angular.

Note that for prerelase versions, that is versions <1.0.0, minor version increases indicate breaking changes, for example releasing version 0.4.0 introduces at least one breaking change compared to version 0.3.0. Patch version increases for prerelease versions indicate bugfixes, refactors, performance improvements, and/or feature additions.

Let's discuss the features and breaking changes of these versions.

Partial Ivy compilation

Spectacular version 0.1.0-0.4.0 are compiled as View Engine-compatible bundles requiring the Angular Compatibility Compiler (NGCC) to be consumed.

As of version 0.5.0, Spectacular is partially Ivy compiled as is the recommended practice for Angular libraries targeting Angular <=12.2.0. Starting with the future Angular version that removes NGCC, View Engine-compatible libraries stop working.

The partial compilation is a performance improvement as most of the library is compiled before being published to a package registry. However, component templates are still required to be compiled in the context of an application.

To use partial Ivy compilation, Spectacular version 0.5.0 requires at least Angular 12.

Standalone feature test provider

With the introduction of standalone Angular components and other standalone Angular APIs starting in Angular version 14 where standalone APIs are considered in developer preview, we start exposing standalone APIs in Spectacular.

Spectacular's first standalone API is a standalone provider factory for Spectacular's Feature testing API.

Spectacular version 0.5.0 introduces provideSpectacularFeatureTest that configures the feature-aware navigation services SpectacularFeatureLocation and SpectacularFeatureRouter for standalone Angular features.

Feature testing a standalone Angular feature using Angular Testing Library and Spectacular:

import {
  provideSpectacularFeatureTest,
  SpectacularAppComponent,
  SpectacularFeatureLocation,
  SpectacularFeatureRouter,
} from '@ngworker/spectacular';
import { render, screen } from '@testing-library/angular';
import { Matcher } from '@testing-library/dom';
import userEvent from '@testing-library/user-event';
import { crisisCenterPath } from '@tour-of-heroes/crisis-center';

const findCrisisCenterHomeGreeting = () =>
  screen.findByText(/welcome to the crisis center/i);
const findCrisisLink = (name: Exclude<Matcher, number>) =>
  screen.findByRole('link', {
    name,
  });
const findNameControl = () => screen.findByPlaceholderText(/name/i);
const findSaveButton = () =>
  screen.findByRole('button', { name: /save/i });
const findSelectedCrisis = (name: Matcher) =>
  screen.findByText(name, {
    selector: '.selected a',
  });
const setup = async () => {
  const user = userEvent.setup();
  const {
    fixture: {
      debugElement: { injector },
    },
  } = await render(SpectacularAppComponent, {
    providers: [
      provideSpectacularFeatureTest({
        featurePath: crisisCenterPath,
      }),
    ],
  });

  return {
    location: injector.get(SpectacularFeatureLocation),
    router: injector.get(SpectacularFeatureRouter),
    user,
  };
};

it('Edit crisis from crisis detail', async () => {
  const { location, router, user } = await setup();
  const crisisId = 2;
  await router.navigate(['~', crisisId]);

  await user.clear(await findNameControl());
  await user.type(
    await findNameControl(),
    'The global temperature is rising'
  );
  await user.click(await findSaveButton());

  expect(
    await findSelectedCrisis(/the global temperature is rising/i)
  ).toBeInTheDocument();
  expect(location.path()).toBe(`~/;id=${crisisId};foo=foo`);
});

it('Edit crisis from crisis center home', async () => {
  const { router, user } = await setup();
  await router.navigateByUrl('~/');

  await user.click(
    await findCrisisLink(/procrastinators meeting delayed again/i)
  );

  await user.clear(await findNameControl());
  await user.type(await findNameControl(), 'Coral reefs are dying');
  await user.click(await findSaveButton());

  expect(await findCrisisCenterHomeGreeting()).toBeInTheDocument();
  expect(
    await findSelectedCrisis(/coral reefs are dying/i)
  ).toBeInTheDocument();
});

Comparing the previous example to the following code snippet, the difference is in the setup SIFERS where we use provideSpectacularFeatureTest instead of SpectacularFeatureTestingModule to adjust the options configuring Angular Testing Library's render function.

Feature test setup SIFERS for an Angular feature module using Angular Testing Library and Spectacular:

import {
  SpectacularAppComponent,
  SpectacularFeatureLocation,
  SpectacularFeatureRouter,
  SpectacularFeatureTestingModule,
} from '@ngworker/spectacular';
import { render } from '@testing-library/angular';
import userEvent from '@testing-library/user-event';
import {
  CrisisCenterModule,
  crisisCenterPath,
} from '@tour-of-heroes/crisis-center';

const setup = async () => {
  const user = userEvent.setup();
  const {
    fixture: {
      debugElement: { injector },
    },
  } = await render(SpectacularAppComponent, {
    imports: [
      SpectacularFeatureTestingModule.withFeature({
        featureModule: CrisisCenterModule,
        featurePath: crisisCenterPath,
      }),
    ],
  });

  return {
    location: injector.get(SpectacularFeatureLocation),
    router: injector.get(SpectacularFeatureRouter),
    user,
  };
};

See the source code for Spectacular for more examples using the feature testing API or visit our documentation.

Spectacular prerelease v0.4 reintroduces the required pipeName option for pipe harnesses

Lars Gyrup Brink Nielsen — Wed, 10 Aug 2022 18:50:29 +0000

Cover art by DALL-E.

In July 2022, we published the version 0.4.0 prerelease of Spectacular, the integration testing library for Angular.

Note that for prerelase versions, that is versions <1.0.0, minor version increases indicate breaking changes, for example releasing version 0.4.0 introduces at least one breaking change compared to version 0.3.0. Patch version increases for prerelease versions indicate bugfixes, refactors, performance improvements, and/or feature additions.

Let's discuss the breaking changes between prerelease versions 0.2.0-0.4.0.

The pipeName option for pipe harnesses is reintroduced

Back in Spectacular prerelease version 0.3.0, released in May 2022, we removed the pipeName option from the createPipeHarness factory to make Angular pipe testing easier. This was a breaking change as the pipeName option was removed entirely in version 0.3.0.

Unfortunately, a function we used internally for determining the pipe name was removed from Angular as it was a leftover from Angular View Engine.

Because of this, Spectacular version 0.4.0 introduces the breaking change of adding back the required pipeName option for createPipeHarness.

Spectacular version 0.3.0:

const harness = createPipeHarness({
  pipe: PowPipe,
  value: 2,
});

Spectacular versions <0.3.0 >=0.4.0:

const harness = createPipeHarness({
  pipe: PowPipe,
  pipeName: 'pow',
  value: 2,
});

Read the documentation for Spectacular's Pipe testing API for full examples of Angular pipe integration tests.

Forem: Lars Gyrup Brink Nielsen

You don't need importProvidersFrom with Angular Material

Standalone Angular application

Classic Angular application

Standalone Angular Material providers

Benefits

Storybook component stories

Component tests

Conclusion

Testing routed components with RouterTestingHarness

Manage Nx library dependencies with the @nx/dependency-checks ESLint rule

Enabling @nx/dependency-checks in .eslintrc.json

Including configuration files in the lint target

Configuring @nx/dependency-checks options

The buildTargets option

The checkMissingDependencies option

The checkObsoleteDependencies option

The checkVersionMismatches option

The ignoredDependencies list

@nx/dependency-checks lint fixers

Ignoring test-setup.ts and similar files

Conclusion

Stop using the defaultProject Nx CLI setting and start using NX_DEFAULT_PROJECT

Why will defaultProject be removed?

What does defaultProject affect?

Running tasks

Running generators

What should I use instead of defaultProject?

Conclusion

Testing Angular routing components with RouterTestingHarness, provideLocationMocks, and provideRouter

providerRouter and provideLocationMocks

RouterTestingHarness

Integrated routing component test suite

Summary

YAML collections: Sequences and mappings

Sequences

Block collection style

Flow collection style

Mappings

Block collection style

Flow collection style

Explicit mapping entries

The local component scope of standalone Angular components

Declarable dependencies

Local component scope

Transitive compilation scope

Maintaining declarable dependencies

Conclusion

Angular Revisited: Standalone Angular applications, the replacement for NgModules

Optional NgModules

NgModule.bootstrap

NgModule.declarations

NgModule.entryComponents

NgModule.exports

NgModule.id

NgModule.jit

NgModule.imports

NgModule.providers

NgModule.schemas

Standalone alternatives for official Angular modules

Standalone vs. classic Angular applications

Angular CLI example for Jest Preview - the visual debugger for Jest

Jest Preview

Angular CLI integration

Docusaurus website for Analog.js - the full-stack meta-framework for Angular using Vite

The analogjs.org website

The home page

Documentation

Packages

End-to-end testing using Cypress and Vite

More to come

Spectacular prerelease v0.5 supports standalone feature tests and uses partial Ivy compilation

Partial Ivy compilation

Standalone feature test provider

Spectacular prerelease v0.4 reintroduces the required pipeName option for pipe harnesses

The pipeName option for pipe harnesses is reintroduced

Why will `defaultProject` be removed?

What does `defaultProject` affect?

What should I use instead of `defaultProject`?