0
# Programmatic API
1

2
The programmatic API provides a fluent interface for building Angular libraries from Node.js applications or build scripts.
3

4
## Capabilities
5

6
### NgPackagr Factory Function
7

8
Creates a new NgPackagr instance with default providers.
9

10
```typescript { .api }
11
/**
12
 * Creates a new NgPackagr instance with default providers
13
 * @returns NgPackagr instance ready for configuration
14
 */
15
function ngPackagr(): NgPackagr;
16
```
17

18
**Usage Example:**
19

20
```typescript
21
import { ngPackagr } from "ng-packagr";
22

23
const packager = ngPackagr();
24
```
25

26
### NgPackagr Class
27

28
Main class for building Angular libraries with a fluent configuration API.
29

30
```typescript { .api }
31
class NgPackagr {
32
  /**
33
   * Sets the path to the user's "ng-package" file
34
   * @param project - Path to package.json, ng-package.json, or ng-package.js
35
   * @returns Self instance for fluent API
36
   */
37
  forProject(project: string): NgPackagr;
38

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

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

54
  /**
55
   * Adds dependency injection providers
56
   * @param providers - Array of providers for dependency injection
57
   * @returns Self instance for fluent API
58
   */
59
  withProviders(providers: Provider[]): NgPackagr;
60

61
  /**
62
   * Overwrites the 'build' transform
63
   * @param transform - Custom build transform
64
   * @returns Self instance for fluent API
65
   */
66
  withBuildTransform(transform: InjectionToken<Transform>): NgPackagr;
67

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

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

82
  /**
83
   * Builds the project and returns an observable
84
   * @returns Observable result of the transformation pipeline
85
   */
86
  buildAsObservable(): Observable<void>;
87
}
88
```
89

90
**Usage Examples:**
91

92
```typescript
93
import { ngPackagr } from "ng-packagr";
94

95
// Basic build
96
await ngPackagr()
97
  .forProject('./ng-package.json')
98
  .build();
99

100
// Build with custom TypeScript config
101
await ngPackagr()
102
  .forProject('./ng-package.json')
103
  .withTsConfig('./tsconfig.lib.json')
104
  .build();
105

106
// Build with options
107
await ngPackagr()
108
  .forProject('./ng-package.json')
109
  .build({
110
    watch: false,
111
    cacheEnabled: true,
112
    cacheDirectory: './custom-cache'
113
  });
114

115
// Watch mode with subscription
116
ngPackagr()
117
  .forProject('./ng-package.json')
118
  .watch({ poll: 1000 })
119
  .subscribe({
120
    next: () => console.log('Build completed'),
121
    error: (err) => console.error('Build failed:', err)
122
  });
123
```
124

125
### NgPackagr Options
126

127
Configuration options for controlling the build process.
128

129
```typescript { .api }
130
interface NgPackagrOptions {
131
  /** Whether or not ng-packagr will watch for file changes and perform an incremental build */
132
  watch?: boolean;
133
  /** Enable/disable build caching (default: true except in CI environments) */
134
  cacheEnabled?: boolean;
135
  /** Custom cache directory path (default: auto-detected system cache) */
136
  cacheDirectory?: string;
137
  /** Enable and define the file watching poll time period in milliseconds */
138
  poll?: number;
139
}
140
```
141

142
### Advanced Usage
143

144
```typescript
145
import { ngPackagr } from "ng-packagr";
146
import { MyCustomTransform } from "./custom-transform";
147

148
// Advanced configuration with custom providers
149
await ngPackagr()
150
  .forProject('./ng-package.json')
151
  .withProviders([
152
    // Custom providers for dependency injection
153
    { provide: 'CUSTOM_TOKEN', useValue: 'custom-value' }
154
  ])
155
  .withBuildTransform(MyCustomTransform)
156
  .build();
157
```
158

159
## Types
160

161
### Required Type Imports
162

163
```typescript { .api }
164
import type { ParsedConfiguration } from '@angular/compiler-cli';
165
import type { Provider, InjectionToken } from 'injection-js';
166
import type { Observable, MonoTypeOperatorFunction } from 'rxjs';
167

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

172
interface BuildGraph {
173
  // Build graph representing package and entry point dependencies
174
}
175
```