Programmatic API

/**
 * Creates a new NgPackagr instance with default providers
 * @returns NgPackagr instance ready for configuration
 */
function ngPackagr(): NgPackagr;

import { ngPackagr } from "ng-packagr";

const packager = ngPackagr();

class NgPackagr {
  /**
   * Sets the path to the user's "ng-package" file
   * @param project - Path to package.json, ng-package.json, or ng-package.js
   * @returns Self instance for fluent API
   */
  forProject(project: string): NgPackagr;

  /**
   * Adds options to ng-packagr
   * @param options - Ng Packagr Options
   * @returns Self instance for fluent API
   * @deprecated Use the options parameter in 'build' and 'watch' methods instead
   */
  withOptions(options: NgPackagrOptions): NgPackagr;

  /**
   * Overwrites the default TypeScript configuration
   * @param defaultValues - A tsconfig providing default values to the compilation
   * @returns Self instance for fluent API
   */
  withTsConfig(defaultValues: ParsedConfiguration | string): NgPackagr;

  /**
   * Adds dependency injection providers
   * @param providers - Array of providers for dependency injection
   * @returns Self instance for fluent API
   */
  withProviders(providers: Provider[]): NgPackagr;

  /**
   * Overwrites the 'build' transform
   * @param transform - Custom build transform
   * @returns Self instance for fluent API
   */
  withBuildTransform(transform: InjectionToken<Transform>): NgPackagr;

  /**
   * Builds the project by kick-starting the 'build' transform
   * @param options - Build options
   * @returns Promise that resolves when build completes
   */
  build(options?: NgPackagrOptions): Promise<void>;

  /**
   * Builds and watches for changes
   * @param options - Build options with watch enabled
   * @returns Observable of build results
   */
  watch(options?: NgPackagrOptions): Observable<void>;

  /**
   * Builds the project and returns an observable
   * @returns Observable result of the transformation pipeline
   */
  buildAsObservable(): Observable<void>;
}

import { ngPackagr } from "ng-packagr";

// Basic build
await ngPackagr()
  .forProject('./ng-package.json')
  .build();

// Build with custom TypeScript config
await ngPackagr()
  .forProject('./ng-package.json')
  .withTsConfig('./tsconfig.lib.json')
  .build();

// Build with options
await ngPackagr()
  .forProject('./ng-package.json')
  .build({
    watch: false,
    cacheEnabled: true,
    cacheDirectory: './custom-cache'
  });

// Watch mode with subscription
ngPackagr()
  .forProject('./ng-package.json')
  .watch({ poll: 1000 })
  .subscribe({
    next: () => console.log('Build completed'),
    error: (err) => console.error('Build failed:', err)
  });

interface NgPackagrOptions {
  /** Whether or not ng-packagr will watch for file changes and perform an incremental build */
  watch?: boolean;
  /** Enable/disable build caching (default: true except in CI environments) */
  cacheEnabled?: boolean;
  /** Custom cache directory path (default: auto-detected system cache) */
  cacheDirectory?: string;
  /** Enable and define the file watching poll time period in milliseconds */
  poll?: number;
}

import { ngPackagr } from "ng-packagr";
import { MyCustomTransform } from "./custom-transform";

// Advanced configuration with custom providers
await ngPackagr()
  .forProject('./ng-package.json')
  .withProviders([
    // Custom providers for dependency injection
    { provide: 'CUSTOM_TOKEN', useValue: 'custom-value' }
  ])
  .withBuildTransform(MyCustomTransform)
  .build();

import type { ParsedConfiguration } from '@angular/compiler-cli';
import type { Provider, InjectionToken } from 'injection-js';
import type { Observable, MonoTypeOperatorFunction } from 'rxjs';

interface Transform extends MonoTypeOperatorFunction<BuildGraph> {
  (source$: Observable<BuildGraph>): Observable<BuildGraph>;
}

interface BuildGraph {
  // Build graph representing package and entry point dependencies
}