0
# ng-packagr
1

2
ng-packagr is a comprehensive build tool specifically designed for compiling and packaging Angular libraries according to the Angular Package Format (APF). It automates the complex process of creating distribution-ready npm packages from TypeScript sources, handling bundling, TypeScript definitions, template/stylesheet processing, and ensuring compatibility with modern Angular build systems.
3

4
## Package Information
5

6
- **Package Name**: ng-packagr
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install ng-packagr`
10

11
## Core Imports
12

13
```typescript
14
import { ngPackagr, NgPackagr, NgPackagrOptions } from "ng-packagr";
15
import { build, execute, version } from "ng-packagr";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { ngPackagr, build, execute, version } = require("ng-packagr");
22
```
23

24
## Basic Usage
25

26
### Programmatic API
27

28
```typescript
29
import { ngPackagr } from "ng-packagr";
30

31
// Basic build
32
await ngPackagr()
33
  .forProject('./ng-package.json')
34
  .build();
35

36
// Build with options
37
await ngPackagr()
38
  .forProject('./ng-package.json')
39
  .build({
40
    watch: false,
41
    cacheEnabled: true
42
  });
43

44
// Watch mode
45
ngPackagr()
46
  .forProject('./ng-package.json')
47
  .watch()
48
  .subscribe();
49
```
50

51
### CLI Usage
52

53
```bash
54
# Basic build
55
ng-packagr -p ng-package.json
56

57
# Watch mode
58
ng-packagr -p ng-package.json -w
59

60
# Custom TypeScript config
61
ng-packagr -p ng-package.json -c tsconfig.lib.json
62
```
63

64
## Architecture
65

66
ng-packagr is built around several key architectural components:
67

68
- **Transform Pipeline**: RxJS-based transformation pipeline that processes the build graph
69
- **Dependency Injection**: Uses `injection-js` for modular, testable architecture
70
- **Build Graph**: Represents package and entry point dependencies as a traversable graph
71
- **File System Abstraction**: Caching and file watching capabilities for incremental builds
72
- **Configuration System**: JSON schema-validated configuration for packages and entry points
73

74
## Capabilities
75

76
### Programmatic API
77

78
Core programmatic interface for building Angular libraries programmatically from Node.js applications or build scripts.
79

80
```typescript { .api }
81
function ngPackagr(): NgPackagr;
82

83
class NgPackagr {
84
  forProject(project: string): NgPackagr;
85
  withOptions(options: NgPackagrOptions): NgPackagr;
86
  withTsConfig(defaultValues: ParsedConfiguration | string): NgPackagr;
87
  withProviders(providers: Provider[]): NgPackagr;
88
  withBuildTransform(transform: InjectionToken<Transform>): NgPackagr;
89
  build(options?: NgPackagrOptions): Promise<void>;
90
  watch(options?: NgPackagrOptions): Observable<void>;
91
  buildAsObservable(): Observable<void>;
92
}
93
```
94

95
[Programmatic API](./programmatic-api.md)
96

97
### Command System
98

99
Command interface for executing build operations with unified error handling and promise-based execution.
100

101
```typescript { .api }
102
interface Command<Arguments, Result> {
103
  (args?: Arguments): Result | Promise<Result>;
104
}
105

106
function execute<A, R>(command: Command<A, R>, args?: A): Promise<R>;
107

108
const build: Command<CliArguments, void>;
109
const version: Command<any, Promise<void>>;
110
```
111

112
[Commands](./commands.md)
113

114
### Configuration System
115

116
Comprehensive configuration system supporting ng-package.json and ng-entrypoint.json files with JSON schema validation.
117

118
```typescript { .api }
119
interface NgPackagrOptions {
120
  watch?: boolean;
121
  cacheEnabled?: boolean;
122
  cacheDirectory?: string;
123
  poll?: number;
124
}
125

126
interface CliArguments {
127
  project: string;
128
  watch?: boolean;
129
  config?: string;
130
  poll?: number;
131
}
132
```
133

134
[Configuration](./configuration.md)
135

136