Angular CLI Schematics: Custom Builders Guide

Setting Up Your Angular Development Environment: Mastering Custom CLI Schematics and Builders

The Angular CLI (Command Line Interface) has revolutionized how developers set up and manage their Angular projects, providing powerful tools to generate code, manage dependencies, and build applications efficiently. Beyond its standard capabilities, the Angular CLI's extensibility through custom schematics and builders allows developers to automate repetitive tasks, enforce coding standards, and create tailored workflows that align with their team's specific needs. Understanding how to leverage these features can significantly enhance your development experience and productivity.

Understanding Angular CLI Schematics and Builders

Angular CLI schematics and builders are powerful tools that can dramatically streamline your development workflow by automating repetitive tasks and enforcing best practices. The Angular CLI comes with built-in schematics that generate components, services, modules, and other Angular artifacts. These schematics follow established patterns and conventions, ensuring consistency across projects. However, every development team has unique requirements and preferences that might not align perfectly with the default schematics.

Custom schematics allow you to extend the Angular CLI's capabilities by creating your own code generation templates and rules. These can range from simple modifications to existing schematics to completely new workflows tailored to your specific needs. Builders, on the other hand, extend the CLI's build and development server capabilities, allowing you to customize how your application is built, served, and tested.

• Schematics automate code generation and file manipulation
• Builders customize build processes and development workflows
• Both tools extend the Angular CLI without modifying its core functionality

By leveraging custom schematics and builders, you can establish standardized patterns across your organization, reduce boilerplate code, and ensure that new projects start with the exact structure and configuration your team requires.

Setting Up Your Angular Development Environment

Before diving into custom schematics and builders, it's essential to have a proper Angular development environment configured. Start by ensuring you have Node.js and npm (Node Package Manager) installed on your system. Angular CLI requires Node.js version 14 or higher, so check your version with node -v and npm with npm -v in your terminal.

Next, install the Angular CLI globally using npm:

npm install -g @angular/cli

Once installed, you can create a new Angular project by running:

ng new my-angular-app

This command sets up a new Angular workspace with a default application. The workspace structure includes a root folder for your project and various configuration files. The Angular CLI uses a workspace-based approach, allowing you to manage multiple applications and libraries within the same project.

Your development environment should include a code editor like Visual Studio Code, which has excellent Angular extensions that provide IntelliSense, debugging, and other helpful features. Additionally, consider setting up a version control system like Git from the start to track changes and collaborate with your team.

With your basic environment in place, you're ready to explore the power of custom schematics and builders to streamline your workflow further.

Creating Custom Schematics

Angular CLI schematics are essentially code generation tools that automate the creation of files and code patterns in your Angular projects. When you run commands like ng generate component, ng service, or ng module, you're using schematics behind the scenes. These schematics follow a defined structure that includes templates, rules, and a schema that describes the options available to the CLI.

Schematics operate by transforming your project's file tree based on a set of rules. They can add, modify, or delete files and content, making them incredibly powerful for maintaining consistency across projects. The default Angular schematics are collected in the @schematics/angular package, which includes schemas for generating various parts of an Angular application.

• Benefits of using Angular schematics:
• Consistent code generation across your team
• Reduced boilerplate code
• Enforced coding standards and best practices
• Time-saving automation of repetitive tasks
• Customizable to fit your project's specific needs

Creating a custom schematic involves several steps, from setting up the project structure to defining the rules that will generate your code. Let's walk through the process of creating a schematic that generates a feature module with specific conventions.

First, you'll need to create a new schematic collection using the Angular CLI:

ng new my-schematic-collection --collection
cd my-schematic-collection

This command generates a new workspace specifically for your schematics. Next, create a new schematic within this collection:

ng generate @schematics/angular:schematic feature-module

This command creates a basic schematic structure with the necessary files. The most important file is feature-module/index.ts, which contains the logic for your schematic. Here's how you might modify it to create a feature module with a predefined structure:

import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
import { addModuleImport } from '@schematics/angular/utility/ast-utils';
import { InsertChange } from '@schematics/angular/utility/change';
import { getWorkspace } from '@schematics/angular/utility/workspace';

export function featureModule(options: any): Rule {
  return async (tree: Tree, context: SchematicContext) => {
    const workspace = await getWorkspace(tree);
    const project = workspace.projects.get(options.project);

    if (!project) {
      throw new Error(`Project ${options.project} not found`);
    }

    // Create the feature module
    const modulePath = `src/app/${options.path}/${options.name}.module.ts`;
    tree.create(modulePath, `
      import { NgModule } from '@angular/core';
      import { CommonModule } from '@angular/common';
      import ${options.name}Component from './${options.name}.component';
      
      @NgModule({
        declarations: [${options.name}Component],
        imports: [CommonModule]
      })
      export class ${options.name}Module { }
    `);

    return tree;
  };
}

The schema.json file is crucial as it defines the options users can provide when running your schematic. For example, a component schematic might include options for specifying the component's name, whether to create a stylesheet, and what type of template to use.

Here's an example of a basic schema.json file:

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "id": "FeatureModule",
  "title": "Feature Module Schematic",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the feature module.",
      "default": "default-feature"
    },
    "path": {
      "type": "string",
      "description": "The path at which to create the feature module.",
      "default": "src/app"
    },
    "project": {
      "type": "string",
      "description": "The target project.",
      "default": ""
    }
  },
  "required": ["name"]
}

After implementing your schematic, you can test it locally by linking it to your project. Run the following command in your schematic collection directory:

npm link

Then, in your Angular project, link the collection:

npm link @my-schematic-collection/schematics

Now you can run your custom schematic using:

ng g @my-schematic-collection:schematics:feature-module --name=user --path=features

Testing is crucial for ensuring your custom schematics work as expected. Angular provides tools for testing schematics through the @angular-devkit/schematics package.

Understanding Angular CLI Builders

While schematics are focused on code generation, builders extend the build process itself. Angular CLI builders are programs that execute specific tasks, such as building, serving, or testing your application. The default Angular CLI includes several builders:

• @angular-devkit/build-angular:browser: For building browser applications
• @angular-devkit/build-angular:server: For building server-side applications
• @angular-devkit/build-angular:karma: For running unit tests with Karma
• @angular-devkit/build-angular:protractor: For running end-to-end tests with Protractor

Builders are defined in the angular.json file, which specifies which builder to use for each command and what options to pass to it. For example, the "build" command in your project uses the @angular-devkit/build-angular:browser builder.

• Key characteristics of Angular CLI builders:
• They are executed using the ng run command
• They can extend or replace existing build processes
• They can perform complex operations beyond simple code generation
• They can be used to optimize, analyze, or transform build outputs

Custom builders allow you to customize the build process to meet your specific needs, such as adding custom code analysis, integrating with third-party tools, or implementing specialized build optimizations.

Creating Custom Builders

Creating a custom builder involves more setup than schematics because builders are essentially Node.js applications that run specific tasks. To create a new builder, you'll need to set up a new project in your Angular workspace:

ng generate @schematics/angular:builder my-custom-builder

This command creates a new builder in the builders/my-custom-builder directory with the following structure:

• builder.json: Defines the builder's schema and implementation
• src/index.ts: Contains the builder's implementation code
• schema.json: Defines the options for the builder

The builder.json file specifies how your builder should be executed and where to find its implementation:

{
  "$schema": "../node_modules/@angular-devkit/architect/src/schema.json",
  "builders": {
    "my-custom-builder": {
      "implementation": "./src/index.js",
      "schema": "./schema.json",
      "description": "A custom builder for Angular projects"
    }
  }
}

Let's explore how to create a custom builder that adds a pre-build optimization step. The implementation in src/index.ts is where you define the actual logic of your builder. This file exports a function that takes options and context, and returns an Observable that emits build results:

import { BuilderContext, BuilderOutput, createBuilder } from '@angular-devkit/architect';
import { Observable } from 'rxjs';
import { spawn } from 'child_process';

function executeCommand(command: string, args: string[]): Promise<void> {
  return new Promise((resolve, reject) => {
    const child = spawn(command, args, { stdio: 'inherit' });
    child.on('close', (code) => {
      if (code !== 0) {
        reject(`Command failed with exit code ${code}`);
      } else {
        resolve();
      }
    });
  });
}

export default createBuilder(async (options: any, context: BuilderContext): Promise<BuilderOutput> => {
  try {
    // Run linting before build
    await executeCommand('ng', ['lint']);
    
    // Execute the default build
    const buildTarget = context.target;
    const result = await context.scheduleTarget(buildTarget, options);
    const output = await result.toPromise();
    
    return { success: output.success };
  } catch (error) {
    context.logger.error(`Build failed: ${error}`);
    return { success: false };
  }
});

The schema.json file defines the options that can be passed to your builder:

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "title": "Custom Builder Schema",
  "type": "object",
  "properties": {
    "option1": {
      "type": "string",
      "description": "Description of option 1"
    },
    "option2": {
      "type": "boolean",
      "default": false,
      "description": "Description of option 2"
    }
  },
  "required": ["option1"]
}

Once your builder is implemented, you can run it using the ng run command:

ng run <project-name>:my-custom-builder --option1=value

You can also integrate your builder into your development workflow by configuring it in the angular.json file, allowing you to run it as part of your regular build process.

Integrating Custom Schematics into Your Project

Once you've created your custom schematics and builders, you need to integrate them into your Angular projects. There are several ways to do this, depending on your use case and distribution method.

For local development, you can link your schematic collection directly to your project. Navigate to your project directory and run:

npm link /path/to/your/schematic-collection

This makes your schematics available in your project without publishing them to npm. You can then use them with the Angular CLI:

ng g @my-schematic-collection:feature-module user

For team-wide usage, you can publish your schematics to a private npm registry or share them through a Git repository. After publishing or sharing, you can add your collection to your project's dependencies:

npm install @my-schematic-collection

Then update your angular.json to reference your schematics:

{
  "schematics": {
    "@my-schematic-collection": {
      "collection": "@my-schematic-collection/schematics",
      "extends": "@schematics/angular"
    }
  }
}

This configuration allows your team to use your custom schematics while still benefiting from the default Angular schematics as a fallback.

Testing and Debugging Custom Schematics and Builders

Testing is crucial for ensuring your custom schematics and builders work as expected. Angular provides tools for testing schematics through the @angular-devkit/schematics package.

To test a schematic, you can create a test file that verifies the changes made to the file system. Here's an example test for the feature module schematic we created earlier:

import { Tree } from '@angular-devkit/schematics';
import { SchematicTestRunner, UnitTestTree } from '@angular-devkit/schematics/testing';
import { createWorkspace } from '@schematics/angular/utility/test';
import * as path from 'path';

describe('Feature Module Schematic', () => {
  const schematicRunner = new SchematicTestRunner(
    '@my-schematic-collection',
    path.join(__dirname, '../collection.json')
  );
  const defaultOptions = {
    name: 'user',
    path: 'feature',
    project: 'test-project'
  };

  let appTree: UnitTestTree;

  beforeEach(async () => {
    appTree = await createWorkspace(schematicRunner, appTree);
  });

  it('should create a feature module', () => {
    const tree = schematicRunner.runSchematic('feature-module', defaultOptions, appTree);
    const files = tree.files;
    expect(files).toContain('/src/app/feature/user.module.ts');
  });

  it('should contain the expected module content', () => {
    const tree = schematicRunner.runSchematic('feature-module', defaultOptions, appTree);
    const content = tree.readContent('/src/app/feature/user.module.ts');
    expect(content).toContain('export class UserModule { }');
  });
});

For debugging, you can use Node.js debugging tools or add console.log statements to track the execution flow. When running schematics, you can also use the --verbose flag to get more detailed output:

ng g @my-schematic-collection:feature-module user --verbose

Best Practices and Real-World Applications

When working with custom schematics and builders, there are several best practices to keep in mind:

• Keep schematics focused and single-purpose
• Provide clear options and documentation
• Test thoroughly before distribution
• Follow Angular's conventions and patterns
• Consider backward compatibility when modifying existing schematics
• Keep your schematics and builders modular and focused
• Use TypeScript for better type safety and maintainability
• Start with simple use cases and gradually build complexity

Real-world applications for custom schematics and builders are virtually limitless. Teams have used them to:

• Generate complete feature modules with all necessary components, services, and routing
• Set up consistent project structures across multiple applications
• Implement custom build processes that include code splitting and optimization
• Create development workflows that automate testing and deployment
• Generate documentation and boilerplate code for common patterns

As you become more comfortable with custom schematics and builders, you can explore more advanced techniques to further enhance your development workflow. One powerful approach is combining schematics and builders to create end-to-end automation solutions. For example, you could create a schematic that sets up a new feature module with components, services, and routing, followed by a builder that optimizes the generated code for production. This combination allows you to maintain consistency while ensuring optimal performance.

When publishing your custom schematics and builders, consider creating an npm package to share them with your team or the wider Angular community. This involves setting up proper package configuration, documentation, and versioning.

It's also important to be aware of common pitfalls when working with custom schematics and builders. These include overcomplicating your solutions, not properly handling file conflicts, and neglecting to test your implementations thoroughly.

Conclusion

Mastering custom Angular CLI schematics and builders is essential for setting up an efficient and productive Angular development environment. By automating repetitive tasks, enforcing coding standards, and extending the build process, you can streamline your workflow and focus on building exceptional applications. Whether you're working on a small personal project or a large team-based application, the ability to customize your development environment with schematics and builders will significantly enhance your Angular development experience.

The combination of schematics for code generation and builders for build process customization provides a powerful toolkit for tailoring the Angular CLI to your specific needs. By investing time in creating and maintaining these tools, you'll reduce manual work, minimize errors, and increase productivity across your entire organization. As you continue to explore these powerful features, you'll discover even more ways to optimize your workflow and deliver high-quality Angular applications more efficiently.

Frequently Asked Questions

• What are Angular CLI schematics?
  Angular CLI schematics are code generation tools that automate the creation of files and code patterns in Angular projects, ensuring consistency across your team.
• How do custom builders enhance Angular development?
  Custom builders extend the build process to include specialized tasks like code analysis, optimization, or integration with third-party tools beyond standard Angular builds.
• What's the difference between schematics and builders?
  Schematics focus on code generation and file manipulation, while builders customize the build and development server processes for your Angular applications.
• How do I test custom Angular CLI schematics?
  You can test schematics using Angular's testing tools like the SchematicTestRunner, which allows you to verify file system changes and content generation.
• What are best practices for creating custom schematics?
  Keep schematics focused and single-purpose, provide clear options and documentation, test thoroughly, follow Angular conventions, and maintain modularity.