0
# License Checker
1
2
License Checker is a comprehensive CLI tool and Node.js library for analyzing license information across package dependency trees. It recursively scans node_modules directories, extracts license data from package.json files and license files, and provides flexible output formats including JSON, CSV, and tree-view display.
3
4
## Package Information
5
6
- **Package Name**: license-checker
7
- **Package Type**: npm
8
- **Language**: Node.js
9
- **Installation**: `npm install -g license-checker` (CLI) or `npm install license-checker` (library)
10
11
## Core Imports
12
13
```javascript
14
const checker = require("license-checker");
15
```
16
17
For ES modules:
18
19
```javascript
20
import * as checker from "license-checker";
21
```
22
23
## Basic Usage
24
25
```javascript
26
const checker = require("license-checker");
27
28
// Scan current directory for licenses
29
checker.init({
30
start: process.cwd()
31
}, function(err, packages) {
32
if (err) {
33
console.error(err);
34
} else {
35
console.log(packages);
36
}
37
});
38
```
39
40
CLI usage:
41
42
```bash
43
# Basic scan of current directory
44
license-checker
45
46
# Scan specific directory
47
license-checker --start /path/to/project
48
49
# Output as JSON
50
license-checker --json --out licenses.json
51
52
# Only production dependencies
53
license-checker --production
54
```
55
56
## Architecture
57
58
License Checker is built around several key components:
59
60
- **Core Engine**: Main scanning and analysis logic that traverses dependency trees using read-installed
61
- **License Detection**: Pattern-based license identification supporting SPDX expressions and common license text recognition
62
- **Output Formatters**: Multiple output formats (tree, JSON, CSV, markdown, summary) for different use cases
63
- **CLI Interface**: Command-line tool with comprehensive options for filtering, formatting, and validation
64
- **File Discovery**: Intelligent license file detection with precedence ordering (LICENSE, LICENCE, COPYING, README)
65
66
## Capabilities
67
68
### License Scanning
69
70
Core license analysis functionality that scans package dependency trees and extracts comprehensive license information from multiple sources including package.json files and license files.
71
72
```javascript { .api }
73
function init(options: ScanOptions, callback: (err: Error | null, data: LicenseData) => void): void;
74
75
interface ScanOptions {
76
start?: string; // Directory to start scanning from
77
production?: boolean; // Only scan production dependencies
78
development?: boolean; // Only scan development dependencies
79
unknown?: boolean; // Report guessed licenses as unknown
80
onlyunknown?: boolean; // Only list packages with unknown licenses
81
direct?: boolean; // Only scan direct dependencies (not transitive)
82
customFormat?: CustomFormat; // Custom output format specification
83
customPath?: string; // Path to custom format JSON file
84
exclude?: string; // Comma-separated licenses to exclude
85
failOn?: string; // Semicolon-separated licenses to fail on
86
onlyAllow?: string; // Semicolon-separated allowed licenses only
87
packages?: string; // Semicolon-separated specific packages to include
88
excludePackages?: string; // Semicolon-separated packages to exclude
89
excludePrivatePackages?: boolean; // Exclude private packages
90
relativeLicensePath?: boolean; // Use relative paths for license files
91
color?: boolean; // Enable colored output
92
}
93
94
interface LicenseData {
95
[packageKey: string]: PackageInfo;
96
}
97
98
interface PackageInfo {
99
licenses: string | string[]; // License identifier(s)
100
repository?: string; // Repository URL
101
publisher?: string; // Package author/publisher
102
email?: string; // Author email
103
url?: string; // Author or package URL
104
path?: string; // Local package path
105
licenseFile?: string; // Path to license file
106
licenseText?: string; // License file content
107
copyright?: string; // Extracted copyright information
108
noticeFile?: string; // Path to NOTICE file
109
private?: boolean; // Whether package is private
110
}
111
```
112
113
[License Scanning](./scanning.md)
114
115
### Output Formatting
116
117
Flexible output formatting system supporting multiple formats for different integration needs including programmatic consumption, reporting, and human-readable display.
118
119
```javascript { .api }
120
function asTree(data: LicenseData): string;
121
function asSummary(data: LicenseData): string;
122
function asCSV(data: LicenseData, customFormat?: CustomFormat, csvComponentPrefix?: string): string;
123
function asMarkDown(data: LicenseData, customFormat?: CustomFormat): string;
124
function print(data: LicenseData): void;
125
126
interface CustomFormat {
127
[fieldName: string]: string | boolean;
128
}
129
```
130
131
[Output Formatting](./formatting.md)
132
133
### File Operations
134
135
License file extraction and JSON parsing utilities for advanced license management workflows.
136
137
```javascript { .api }
138
function asFiles(data: LicenseData, outDir: string): void;
139
function parseJson(jsonPath: string): object | Error;
140
```
141
142
[File Operations](./file-operations.md)
143
144
### Command Line Interface
145
146
Comprehensive CLI tool for license analysis with flexible output options and validation controls.
147
148
```bash { .api }
149
# Basic usage
150
license-checker [options]
151
152
# Common options:
153
--start <path> # Starting directory (default: current directory)
154
--production # Production dependencies only
155
--development # Development dependencies only
156
--json # JSON output format
157
--csv # CSV output format
158
--markdown # Markdown output format
159
--summary # License usage summary
160
--out <file> # Write output to file
161
--unknown # Report guessed licenses as unknown
162
--onlyunknown # Show only unknown licenses
163
--direct # Direct dependencies only
164
--exclude <licenses> # Exclude specific licenses (comma-separated)
165
--failOn <licenses> # Fail on specific licenses (semicolon-separated)
166
--onlyAllow <licenses> # Only allow specific licenses (semicolon-separated)
167
--packages <packages> # Include specific packages (semicolon-separated)
168
--excludePackages <packages> # Exclude specific packages (semicolon-separated)
169
--excludePrivatePackages # Exclude private packages
170
--relativeLicensePath # Use relative license file paths
171
--customPath <file> # Custom format specification file
172
--csvComponentPrefix <prefix> # CSV component column prefix
173
--files <dir> # Extract license files to directory
174
```
175
176
**Usage Examples:**
177
178
```bash
179
# Basic scan of current directory
180
license-checker
181
182
# Scan specific directory with JSON output
183
license-checker --start ./my-project --json --out licenses.json
184
185
# Production dependencies only
186
license-checker --production --summary
187
188
# Fail on GPL licenses
189
license-checker --failOn "GPL-2.0;GPL-3.0;LGPL-2.1"
190
191
# Only allow specific licenses
192
license-checker --onlyAllow "MIT;Apache-2.0;BSD-3-Clause"
193
194
# Generate compliance report
195
license-checker --csv --out report.csv --files ./extracted-licenses
196
197
# Custom format with markdown output
198
license-checker --customPath ./format.json --markdown --out README-licenses.md
199
```
200
201
## Types
202
203
```javascript { .api }
204
interface ScanOptions {
205
start?: string; // Starting directory path
206
production?: boolean; // Production dependencies only
207
development?: boolean; // Development dependencies only
208
unknown?: boolean; // Report guessed licenses as unknown
209
onlyunknown?: boolean; // Show only unknown licenses
210
direct?: boolean; // Direct dependencies only
211
customFormat?: CustomFormat; // Custom output format
212
customPath?: string; // Path to custom format file
213
exclude?: string; // Licenses to exclude (comma-separated)
214
failOn?: string; // Licenses to fail on (semicolon-separated)
215
onlyAllow?: string; // Only allowed licenses (semicolon-separated)
216
packages?: string; // Specific packages to include
217
excludePackages?: string; // Packages to exclude
218
excludePrivatePackages?: boolean; // Exclude private packages
219
relativeLicensePath?: boolean; // Use relative license file paths
220
color?: boolean; // Enable colored output
221
}
222
223
interface PackageInfo {
224
licenses: string | string[]; // License identifiers
225
repository?: string; // Repository URL
226
publisher?: string; // Package publisher
227
email?: string; // Publisher email
228
url?: string; // Publisher/package URL
229
path?: string; // Package path
230
licenseFile?: string; // License file path
231
licenseText?: string; // License content
232
copyright?: string; // Copyright information
233
noticeFile?: string; // Notice file path
234
private?: boolean; // Private package flag
235
}
236
237
interface LicenseData {
238
[packageName: string]: PackageInfo;
239
}
240
241
interface CustomFormat {
242
[fieldName: string]: string | boolean;
243
}
244
```