1 | # egg-bin
|
2 |
|
3 | [![NPM version][npm-image]][npm-url]
|
4 | [![build status][travis-image]][travis-url]
|
5 | [![Test coverage][codecov-image]][codecov-url]
|
6 | [![David deps][david-image]][david-url]
|
7 | [![Known Vulnerabilities][snyk-image]][snyk-url]
|
8 | [![npm download][download-image]][download-url]
|
9 |
|
10 | [npm-image]: https://img.shields.io/npm/v/egg-bin.svg?style=flat-square
|
11 | [npm-url]: https://npmjs.org/package/egg-bin
|
12 | [travis-image]: https://img.shields.io/travis/eggjs/egg-bin.svg?style=flat-square
|
13 | [travis-url]: https://travis-ci.org/eggjs/egg-bin
|
14 | [codecov-image]: https://codecov.io/gh/eggjs/egg-bin/branch/master/graph/badge.svg
|
15 | [codecov-url]: https://codecov.io/gh/eggjs/egg-bin
|
16 | [david-image]: https://img.shields.io/david/eggjs/egg-bin.svg?style=flat-square
|
17 | [david-url]: https://david-dm.org/eggjs/egg-bin
|
18 | [snyk-image]: https://snyk.io/test/npm/egg-bin/badge.svg?style=flat-square
|
19 | [snyk-url]: https://snyk.io/test/npm/egg-bin
|
20 | [download-image]: https://img.shields.io/npm/dm/egg-bin.svg?style=flat-square
|
21 | [download-url]: https://npmjs.org/package/egg-bin
|
22 |
|
23 | egg developer tool, extends [common-bin].
|
24 |
|
25 | ---
|
26 |
|
27 | ## Install
|
28 |
|
29 | ```bash
|
30 | $ npm i egg-bin --save-dev
|
31 | ```
|
32 |
|
33 | ## Usage
|
34 |
|
35 | Add `egg-bin` to `package.json` scripts:
|
36 |
|
37 | ```json
|
38 | {
|
39 | "scripts": {
|
40 | "dev": "egg-bin dev",
|
41 | "debug": "egg-bin debug",
|
42 | "test-local": "egg-bin test",
|
43 | "test": "npm run lint -- --fix && npm run test-local",
|
44 | "cov": "egg-bin cov",
|
45 | "lint": "eslint .",
|
46 | "pkgfiles": "egg-bin pkgfiles",
|
47 | "autod": "egg-bin autod",
|
48 | "ci": "npm run lint && npm run autod -- --check && npm run pkgfiles -- --check && npm run cov"
|
49 | }
|
50 | }
|
51 | ```
|
52 |
|
53 | ## Command
|
54 |
|
55 | All the commands support these specific v8 options:
|
56 |
|
57 | - `--debug`
|
58 | - `--inspect`
|
59 | - `--harmony*`
|
60 | - `--es_staging`
|
61 |
|
62 | ```bash
|
63 | $ egg-bin [command] --debug --es_staging
|
64 | ```
|
65 |
|
66 | if `process.env.NODE_DEBUG_OPTION` is provided (WebStorm etc), will use it as debug options.
|
67 |
|
68 | ### dev
|
69 |
|
70 | Start dev cluster on `local` env, it will start a master, an agent and a worker.
|
71 |
|
72 | ```bash
|
73 | $ egg-bin dev
|
74 | ```
|
75 |
|
76 | ##### options
|
77 |
|
78 | - `--framework` egg web framework root path.
|
79 | - `--baseDir` application's root path, default to `process.cwd()`.
|
80 | - `--port` server port, default to `7001`.
|
81 | - `--cluster` worker process number, skip this argvs will start only `1` worker, provide this without value will start `cpu` count worker.
|
82 | - `--sticky` start a sticky cluster server, default to `false`.
|
83 |
|
84 | ### debug
|
85 |
|
86 | Debug egg app with [V8 Inspector Integration](https://nodejs.org/api/debugger.html#debugger_v8_inspector_integration_for_node_js).
|
87 |
|
88 | automatically detect the protocol, use the new `inspector` when the targeted runtime >=7.0.0 .
|
89 |
|
90 | use [inspector-proxy](https://github.com/whxaxes/inspector-proxy) to proxy worker debug, so you don't need to worry about reload.
|
91 |
|
92 | ```bash
|
93 | $ egg-bin debug --debug-port=9229 --proxy=9999
|
94 | ```
|
95 |
|
96 | ##### options
|
97 |
|
98 | - all `egg-bin dev` options is accepted.
|
99 | - `--proxy=9999` worker debug proxy port.
|
100 |
|
101 |
|
102 | ### test
|
103 |
|
104 | Using [mocha] with [co-mocha] to run test.
|
105 |
|
106 | [power-assert] is the default `assert` library, and [intelli-espower-loader] will be auto required.
|
107 |
|
108 | ```bash
|
109 | $ egg-bin test [files] [options]
|
110 | ```
|
111 |
|
112 | - `files` is optional, default to `test/**/*.test.js`
|
113 | - `test/fixtures`, `test/node_modules` is always exclude.
|
114 |
|
115 | #### auto require `test/.setup.js`
|
116 |
|
117 | If `test/.setup.js` file exists, it will be auto require as the first test file.
|
118 |
|
119 | ```js
|
120 | test
|
121 | ├── .setup.js
|
122 | └── foo.test.js
|
123 | ```
|
124 |
|
125 | #### options
|
126 |
|
127 | You can pass any mocha argv.
|
128 |
|
129 | - `--require` require the given module
|
130 | - `--grep` only run tests matching <pattern>
|
131 | - `--timeout` milliseconds, default to 30000
|
132 | - `--full-trace` display the full stack trace, default to false.
|
133 | - see more at https://mochajs.org/#usage
|
134 |
|
135 | #### environment
|
136 |
|
137 | Environment is also support, will use it if options not provide.
|
138 |
|
139 | You can set `TESTS` env to set the tests directory, it support [glob] grammar.
|
140 |
|
141 | ```bash
|
142 | TESTS=test/a.test.js egg-bin test
|
143 | ```
|
144 |
|
145 | And the reporter can set by the `TEST_REPORTER` env, default is `spec`.
|
146 |
|
147 | ```bash
|
148 | TEST_REPORTER=doc egg-bin test
|
149 | ```
|
150 |
|
151 | The test timeout can set by `TEST_TIMEOUT` env, default is `30000` ms.
|
152 |
|
153 | ```bash
|
154 | TEST_TIMEOUT=2000 egg-bin test
|
155 | ```
|
156 |
|
157 | ### cov
|
158 |
|
159 | Using [istanbul] to run code coverage, it support all test params above.
|
160 |
|
161 | Coverage reporter will output text-summary, json and lcov.
|
162 |
|
163 | #### options
|
164 |
|
165 | You can pass any mocha argv.
|
166 |
|
167 | - `-x` add dir ignore coverage, support multiple argv
|
168 | - `--prerequire` prerequire files for coverage instrument, you can use this options if load files slowly when call `mm.app` or `mm.cluster`
|
169 | - also support all test params above.
|
170 |
|
171 | #### environment
|
172 |
|
173 | You can set `COV_EXCLUDES` env to add dir ignore coverage.
|
174 |
|
175 | ```bash
|
176 | $ COV_EXCLUDES="app/plugins/c*,app/autocreate/**" egg-bin cov
|
177 | ```
|
178 |
|
179 | ### pkgfiles
|
180 |
|
181 | Generate `pkg.files` automatically before npm publish, see [ypkgfiles] for detail
|
182 |
|
183 | ```bash
|
184 | $ egg-bin pkgfiles
|
185 | ```
|
186 |
|
187 | ### autod
|
188 |
|
189 | Generate `pkg.dependencies` and `pkg.devDependencies` automatically, see [autod] for detail
|
190 |
|
191 | ```bash
|
192 | $ egg-bin autod
|
193 | ```
|
194 |
|
195 | ## Custom egg-bin for your team
|
196 |
|
197 | You maybe need a custom egg-bin to implement more custom features if your team has develop a framework base on egg.
|
198 |
|
199 | Now you can implement a [Command](lib/command.js) sub class to do that.
|
200 | Or you can just override the exists command.
|
201 |
|
202 | See more at [common-bin].
|
203 |
|
204 | ### Example: Add [nsp] for security scan
|
205 |
|
206 | [nsp] has provide a useful security scan feature.
|
207 |
|
208 | This example will show you how to add a new `NspCommand` to create a new `egg-bin` tool.
|
209 |
|
210 | - Full demo: [my-egg-bin](test/fixtures/my-egg-bin)
|
211 |
|
212 | #### [my-egg-bin](test/fixtures/my-egg-bin/index.js)
|
213 |
|
214 | ```js
|
215 | const EggBinCommand = require('egg-bin');
|
216 |
|
217 | class MyEggBinCommand extends EggBinCommand {
|
218 | constructor(rawArgv) {
|
219 | super(rawArgv);
|
220 | this.usage = 'Usage: egg-bin [command] [options]';
|
221 |
|
222 | // load directory
|
223 | this.load(path.join(__dirname, 'lib/cmd'));
|
224 | }
|
225 | }
|
226 |
|
227 | module.exports = MyEggBinCommand;
|
228 | ```
|
229 |
|
230 | #### [NspCommand](test/fixtures/my-egg-bin/lib/cmd/nsp.js)
|
231 |
|
232 | ```js
|
233 | const Command = require('egg-bin').Command;
|
234 |
|
235 | class NspCommand extends Command {
|
236 | * run({ cwd, argv }) {
|
237 | console.log('run nsp check at %s with %j', cwd, argv);
|
238 | }
|
239 |
|
240 | description() {
|
241 | return 'nsp check';
|
242 | }
|
243 | }
|
244 |
|
245 | module.exports = NspCommand;
|
246 | ```
|
247 |
|
248 | #### [my-egg-bin.js](test/fixtures/my-egg-bin/bin/my-egg-bin.js)
|
249 |
|
250 | ```js
|
251 | #!/usr/bin/env node
|
252 |
|
253 | 'use strict';
|
254 | const Command = require('..');
|
255 | new Command().start();
|
256 | ```
|
257 |
|
258 | #### Run result
|
259 |
|
260 | ```bash
|
261 | $ my-egg-bin nsp
|
262 |
|
263 | run nsp check at /foo/bar with {}
|
264 | ```
|
265 |
|
266 | ## License
|
267 |
|
268 | [MIT](LICENSE)
|
269 |
|
270 |
|
271 | [mocha]: https://mochajs.org
|
272 | [co-mocha]: https://npmjs.com/co-mocha
|
273 | [glob]: https://github.com/isaacs/node-glob
|
274 | [istanbul]: https://github.com/gotwarlost/istanbul
|
275 | [nsp]: https://npmjs.com/nsp
|
276 | [iron-node]: https://github.com/s-a/iron-node
|
277 | [intelli-espower-loader]: https://github.com/power-assert-js/intelli-espower-loader
|
278 | [power-assert]: https://github.com/power-assert-js/power-assert
|
279 | [ypkgfiles]: https://github.com/popomore/ypkgfiles
|
280 | [common-bin]: https://github.com/node-modules/common-bin
|
281 | [autod]: https://github.com/node-modules/autod
|