CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-schematics--angular

Angular schematics collection providing code generators for Angular applications, components, services, and other constructs.

—

Pending
Overview
Eval results
Files

dependency-management.mddocs/

Dependency Management

Functions for managing package.json dependencies within schematics, including adding, removing, and modifying npm packages with automatic installation handling.

Capabilities

Adding Dependencies

Primary function for adding npm packages to a project's package.json.

/**
 * Adds a package dependency to package.json and optionally schedules installation
 * @param options - Dependency configuration options
 * @returns Rule that adds the dependency
 */
function addDependency(options: AddDependencyOptions): Rule;

interface AddDependencyOptions {
  /** Dependency type (dependencies, devDependencies, peerDependencies) */
  type: DependencyType;
  /** Package name */
  name: string;
  /** Package version */
  version: string;
  /** Optional npm registry URL */
  registry?: string;
  /** Installation behavior (None, Auto, Always) */
  installBehavior?: InstallBehavior;
  /** Behavior when dependency already exists */
  existingBehavior?: ExistingBehavior;
  /** Target project name */
  project?: string;
}

enum DependencyType {
  Default = 'dependencies',
  Dev = 'devDependencies',
  Peer = 'peerDependencies'
}

enum InstallBehavior {
  /** Do not schedule npm install */
  None,
  /** Automatically determine if install is needed */
  Auto,
  /** Always schedule npm install */
  Always
}

enum ExistingBehavior {
  /** Skip if dependency already exists */
  Skip,
  /** Replace existing dependency version */
  Replace
}

Usage Examples:

import { addDependency, DependencyType, InstallBehavior } from '@schematics/angular/utility';

// Add runtime dependency
export function addAngularMaterial(): Rule {
  return addDependency({
    type: DependencyType.Default,
    name: '@angular/material',
    version: '^15.0.0',
    installBehavior: InstallBehavior.Always
  });
}

// Add development dependency  
export function addTestingLibrary(): Rule {
  return addDependency({
    type: DependencyType.Dev,
    name: '@testing-library/angular',
    version: '^13.0.0',
    existingBehavior: ExistingBehavior.Replace,
    installBehavior: InstallBehavior.Auto
  });
}

// Add peer dependency
export function addPeerDep(): Rule {
  return addDependency({
    type: DependencyType.Peer,
    name: 'rxjs',
    version: '^7.5.0',
    installBehavior: InstallBehavior.None
  });
}

Package.json Manipulation

Low-level functions for directly manipulating package.json files.

/**
 * Adds a dependency directly to package.json without installation
 * @param tree - Virtual file system tree
 * @param dependency - Dependency to add
 * @param pkgJsonPath - Optional path to package.json (defaults to '/package.json')
 */
function addPackageJsonDependency(
  tree: Tree, 
  dependency: NodeDependency, 
  pkgJsonPath?: string
): void;

/**
 * Retrieves a dependency from package.json
 * @param tree - Virtual file system tree
 * @param name - Package name to retrieve
 * @param pkgJsonPath - Optional path to package.json
 * @returns Dependency object or null if not found
 */
function getPackageJsonDependency(
  tree: Tree, 
  name: string, 
  pkgJsonPath?: string
): NodeDependency | null;

/**
 * Removes a dependency from package.json
 * @param tree - Virtual file system tree
 * @param name - Package name to remove
 * @param pkgJsonPath - Optional path to package.json
 */
function removePackageJsonDependency(
  tree: Tree, 
  name: string, 
  pkgJsonPath?: string
): void;

interface NodeDependency {
  /** Package name */  
  name: string;
  /** Package version */
  version: string;
  /** Dependency type */
  type: NodeDependencyType;
  /** Whether dependency was overwritten */
  overwrite?: boolean;
}

enum NodeDependencyType {
  Default = 'dependencies',
  Dev = 'devDependencies',
  Peer = 'peerDependencies',
  Optional = 'optionalDependencies'
}

Usage Example:

import { 
  addPackageJsonDependency, 
  getPackageJsonDependency,
  NodeDependencyType 
} from '@schematics/angular/utility';

export function managePackages(): Rule {
  return (tree: Tree) => {
    // Check if package exists
    const existing = getPackageJsonDependency(tree, '@angular/core');
    
    if (!existing) {
      // Add package directly
      addPackageJsonDependency(tree, {
        name: '@angular/core',
        version: '^15.0.0',
        type: NodeDependencyType.Default
      });
    }
    
    return tree;
  };
}

Version Management

Utilities for managing package versions and latest version information.

/**
 * Object containing latest stable versions of Angular packages
 * Updated with each release of @schematics/angular
 */
declare const latestVersions: {
  /** Latest Angular framework version */
  Angular: string;
  /** Latest Angular DevKit Build Angular version */
  DevkitBuildAngular: string;
  /** Latest Angular DevKit Schematics version */
  DevkitSchematics: string;
  /** Latest Angular CLI version */
  AngularCli: string;
  /** Latest RxJS version */
  RxJs: string;
  /** Latest TypeScript version */
  TypeScript: string;
  /** Latest Zone.js version */
  ZoneJs: string;
  /** Latest Angular PWA version */
  AngularPWA: string;
  /** Additional package versions */
  [packageName: string]: string;
};

Usage Example:

import { addDependency, latestVersions, DependencyType } from '@schematics/angular/utility';

export function addLatestAngular(): Rule {
  return addDependency({
    type: DependencyType.Default,
    name: '@angular/core',
    version: latestVersions.Angular // Uses latest stable version
  });
}

Installation Tasks

Functions for scheduling npm/yarn installation tasks after dependency changes.

/**
 * Schedules a package installation task
 * Note: This is handled automatically by addDependency when installBehavior is set
 * @param context - Schematic context
 * @param packageManager - Package manager to use ('npm' | 'yarn' | 'pnpm')
 * @returns Task ID
 */
function schedulePackageInstall(
  context: SchematicContext,
  packageManager?: string
): TaskId;

Additional Dependency Utilities

Extended dependency management functions available via direct import.

// Import from @schematics/angular/utility/dependencies
import { 
  addPackageJsonDependency,
  getPackageJsonDependency,
  removePackageJsonDependency,
  NodeDependency,
  NodeDependencyType
} from '@schematics/angular/utility/dependencies';

/**
 * Adds a dependency directly to package.json without installation
 * @param tree - Virtual file system tree
 * @param dependency - Dependency to add
 * @param pkgJsonPath - Optional path to package.json (defaults to '/package.json')
 */
function addPackageJsonDependency(
  tree: Tree, 
  dependency: NodeDependency, 
  pkgJsonPath?: string
): void;

/**
 * Retrieves a dependency from package.json
 * @param tree - Virtual file system tree
 * @param name - Package name to retrieve
 * @param pkgJsonPath - Optional path to package.json
 * @returns Dependency object or null if not found
 */
function getPackageJsonDependency(
  tree: Tree, 
  name: string, 
  pkgJsonPath?: string
): NodeDependency | null;

/**
 * Removes a dependency from package.json
 * @param tree - Virtual file system tree
 * @param name - Package name to remove
 * @param pkgJsonPath - Optional path to package.json
 */
function removePackageJsonDependency(
  tree: Tree, 
  name: string, 
  pkgJsonPath?: string
): void;

interface NodeDependency {
  /** Package name */  
  name: string;
  /** Package version */
  version: string;
  /** Dependency type */
  type: NodeDependencyType;
  /** Whether dependency was overwritten */
  overwrite?: boolean;
}

enum NodeDependencyType {
  Default = 'dependencies',
  Dev = 'devDependencies',
  Peer = 'peerDependencies',
  Optional = 'optionalDependencies'
}

Advanced Usage

Conditional Dependencies

import { addDependency, DependencyType, ExistingBehavior } from '@schematics/angular/utility';

export function conditionalDependencies(): Rule {
  return async (tree: Tree, context: SchematicContext) => {
    // Check Angular version before adding dependency
    const packageJson = tree.readText('/package.json');
    const pkg = JSON.parse(packageJson);
    const angularVersion = pkg.dependencies?.['@angular/core'];
    
    if (angularVersion && angularVersion.includes('15')) {
      return addDependency({
        type: DependencyType.Default,
        name: '@angular/material',
        version: '^15.0.0',
        existingBehavior: ExistingBehavior.Replace
      });
    }
    
    return noop();
  };
}

Multiple Dependencies

import { chain } from '@angular-devkit/schematics';
import { addDependency, DependencyType } from '@schematics/angular/utility';

export function addMultipleDependencies(): Rule {
  return chain([
    addDependency({
      type: DependencyType.Default,
      name: '@angular/material',
      version: '^15.0.0'
    }),
    addDependency({
      type: DependencyType.Default,  
      name: '@angular/cdk',
      version: '^15.0.0'
    }),
    addDependency({
      type: DependencyType.Dev,
      name: '@angular/material-moment-adapter',
      version: '^15.0.0'
    })
  ]);
}

Custom Registry

export function addFromPrivateRegistry(): Rule {
  return addDependency({
    type: DependencyType.Default,
    name: '@company/shared-lib',
    version: '^1.0.0',
    registry: 'https://npm.company.com/',
    installBehavior: InstallBehavior.Always
  });
}

Install with Tessl CLI

npx tessl i tessl/npm-schematics--angular

docs

ast-utilities.md

dependency-management.md

index.md

schematics.md

standalone-utilities.md

workspace-utilities.md

tile.json