1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
# ncc
[](https://github.com/vercel/ncc/actions?workflow=CI)
[](https://codecov.io/gh/vercel/ncc)
Simple CLI for compiling a Node.js module into a single file,
together with all its dependencies, gcc-style.
## Motivation
- Publish minimal packages to npm
- Only ship relevant app code to serverless environments
- Don't waste time configuring bundlers
- Generally faster bootup time and less I/O overhead
- Compiled language-like experience (e.g.: `go`)
## Design goals
- Zero configuration
- TypeScript built-in
- Only supports Node.js programs as input / output
- Support all Node.js patterns and npm modules
## Usage
### Installation
```bash
npm i -g @vercel/ncc
```
### Usage
```bash
$ ncc <cmd> <opts>
```
Eg:
```bash
$ ncc build input.js -o dist
```
Outputs the Node.js compact build of `input.js` into `dist/index.js`.
> Note: If the input file is using a `.cjs` extension, then so will the corresponding output file.
> This is useful for packages that want to use `.js` files as modules in native Node.js using
> a `"type": "module"` in the package.json file.
#### Commands:
```
build <input-file> [opts]
run <input-file> [opts]
cache clean|dir|size
help
version
```
#### Options:
```
-o, --out [file] Output directory for build (defaults to dist)
-m, --minify Minify output
-C, --no-cache Skip build cache population
-s, --source-map Generate source map
--no-source-map-register Skip source-map-register source map support
-e, --external [mod] Skip bundling 'mod'. Can be used many times
-q, --quiet Disable build summaries / non-error outputs
-w, --watch Start a watched build
--v8-cache Emit a build using the v8 compile cache
--license [file] Adds a file containing licensing information to the output
--stats-out [file] Emit webpack stats as json to the specified output file
```
### Execution Testing
For testing and debugging, a file can be built into a temporary directory and executed with full source maps support with the command:
```bash
$ ncc run input.js
```
### With TypeScript
The only requirement is to point `ncc` to `.ts` or `.tsx` files. A `tsconfig.json`
file is necessary. Most likely you want to indicate `es2015` support:
```json
{
"compilerOptions": {
"target": "es2015",
"moduleResolution": "node"
}
}
```
### Package Support
Some packages may need some extra options for ncc support in order to better work with the static analysis.
See [package-support.md](package-support.md) for some common packages and their usage with ncc.
### Programmatically From Node.js
```js
require('@vercel/ncc')('/path/to/input', {
// provide a custom cache path or disable caching
cache: "./custom/cache/path" | false,
// externals to leave as requires of the build
externals: ["externalpackage"],
// directory outside of which never to emit assets
filterAssetBase: process.cwd(), // default
minify: false, // default
sourceMap: false, // default
sourceMapBasePrefix: '../', // default treats sources as output-relative
// when outputting a sourcemap, automatically include
// source-map-support in the output file (increases output by 32kB).
sourceMapRegister: true, // default
watch: false, // default
license: '', // default does not generate a license file
v8cache: false, // default
quiet: false, // default
debugLog: false // default
}).then(({ code, map, assets }) => {
console.log(code);
// Assets is an object of asset file names to { source, permissions, symlinks }
// expected relative to the output code (if any)
})
```
When `watch: true` is set, the build object is not a promise, but has the following signature:
```js
{
// handler re-run on each build completion
// watch errors are reported on "err"
handler (({ err, code, map, assets }) => { ... })
// handler re-run on each rebuild start
rebuild (() => {})
// close the watcher
void close ();
}
```
## Caveats
- Files / assets are relocated based on a [static evaluator](https://github.com/zeit/webpack-asset-relocator-loader#how-it-works). Dynamic non-statically analyzable asset loads may not work out correctly
|
