README.md 8.7 KB
Newer Older
S
😋  
sorrycc 已提交
1 2
# roadhog

S
😶  
sorrycc 已提交
3 4 5 6 7
[![NPM version](https://img.shields.io/npm/v/roadhog.svg?style=flat)](https://npmjs.org/package/roadhog)
[![Build Status](https://img.shields.io/travis/sorrycc/roadhog.svg?style=flat)](https://travis-ci.org/sorrycc/roadhog)
[![NPM downloads](http://img.shields.io/npm/dm/roadhog.svg?style=flat)](https://npmjs.org/package/roadhog)
[![Dependencies](https://david-dm.org/sorrycc/roadhog/status.svg)](https://david-dm.org/sorrycc/roadhog)

C
chencheng 已提交
8
[查看中文版](./README_zh-cn.md)
S
sorrycc 已提交
9

C
chencheng 已提交
10
Roadhog is a cli tool with `dev``build` and `test` commands. It's based on react-dev-utils and is consistent with the experience of create-react-app. You can imagine this is a configurable version of create-react-app.
S
😬  
sorrycc 已提交
11

C
chencheng 已提交
12
## Docs
C
chencheng 已提交
13 14 15

* [2.0 发布日志](https://github.com/sorrycc/blog/issues/55)
* [Migrate from 1.x](./migrate-from-1.x.md)
C
chencheng 已提交
16
* [1.x docs](https://github.com/sorrycc/roadhog/blob/1.x/README_en-us.md)
S
😋  
sorrycc 已提交
17

C
chencheng 已提交
18 19 20 21 22
## Features
* 📦 out of the box React application development tools, built-in css-modules, babel, postcss, HMR, etc.
* 🐠 create-react-app experience
* 🚨 webpack configuration in JSON format
* 🔥 mock
C
chencheng 已提交
23
* ✂️ test based on jest, ui test with enzyme
S
😋  
sorrycc 已提交
24

C
chencheng 已提交
25
## Getting started
S
😋  
sorrycc 已提交
26
```bash
C
chencheng 已提交
27
## Install globally or locally
S
😋  
sorrycc 已提交
28 29
$ npm i roadhog -g

C
chencheng 已提交
30 31 32
## Check version
$ roadhog -v
2.0.0
S
😋  
sorrycc 已提交
33

C
chencheng 已提交
34 35
## Local development
$ roadhog dev
S
😋  
sorrycc 已提交
36

C
chencheng 已提交
37
## Build
S
😋  
sorrycc 已提交
38
$ roadhog build
C
chencheng 已提交
39
$ NO_COMPRESS=1 roadhog build
S
😋  
sorrycc 已提交
40

C
chencheng 已提交
41
## Test
C
CHEN Kan 已提交
42
$ roadhog test
S
😋  
sorrycc 已提交
43 44
```

C
chencheng 已提交
45 46
## Mock
roadhog dev support mock, configured in  `.roadhogrc.mock.js`.
S
📖  
sorrycc 已提交
47

C
chencheng 已提交
48
e.g.
S
📖  
sorrycc 已提交
49 50 51

```js
export default {
C
chencheng (云谦) 已提交
52
  // Support type as Object and Array
S
📖  
sorrycc 已提交
53 54
  'GET /api/users': { users: [1,2] },

C
chencheng (云谦) 已提交
55
  // Method like GET or POST can be omitted
S
📖  
sorrycc 已提交
56 57
  '/api/users/1': { id: 1 },

C
chencheng (云谦) 已提交
58
  // Support for custom functions, the API is the same as express@4
S
📖  
sorrycc 已提交
59 60 61 62
  'POST /api/users/create': (req, res) => { res.end('OK'); },
};
```

C
chencheng 已提交
63
## Use the public directory
C
chencheng (云谦) 已提交
64

C
chencheng 已提交
65
Files in the public directory would be copied to the output directory (by default `./dist`) on the dev and build. So favicon, iconfont, html, html quoted pictures could be stored here.
S
📖  
sorrycc 已提交
66

C
chencheng (云谦) 已提交
67 68
## Configuration

C
chencheng (云谦) 已提交
69
roadhog's webpack part is based on the af-webpack's implementation. For configuration, create `.webpackrc` in the project root. The format is JSON, e.g.
S
😴  
sorrycc 已提交
70

C
chencheng 已提交
71
```js
S
😴  
sorrycc 已提交
72
{
C
chencheng 已提交
73
  "externals": { "react": "window.React" }
S
😴  
sorrycc 已提交
74 75 76
}
```

C
chencheng (云谦) 已提交
77
If you prefer JS configuration, or need to do some programming or abstract judgment, you can use `.webpackrc.js` configuration file, support ES6 syntax, e.g.
S
😴  
sorrycc 已提交
78

C
chencheng 已提交
79 80 81 82
```js
export default {
  externals: { react: 'window.React' },
}
S
😴  
sorrycc 已提交
83 84
```

C
chencheng (云谦) 已提交
85
Index:
C
chencheng 已提交
86 87 88 89 90 91

* [entry](#entry)
* [theme](#theme)
* [define](#define)
* [externals](#externals)
* [alias](#alias)
D
dongge 已提交
92
* [extraResolveExtensions](#extraresolveextensions)
C
chencheng 已提交
93
* [browserslist](#browserslist)
C
chencheng (云谦) 已提交
94 95
* [publicPath](#publicpath)
* [outputPath](#outputpath)
C
chencheng 已提交
96 97
* [devtool](#devtool)
* [commons](#commons)
98
* [hash](#hash)
C
chencheng 已提交
99
* [html](#html)
C
chencheng (云谦) 已提交
100 101 102 103 104
* [disableCSSModules](#disablecssmodules)
* [disableCSSSourceMap](#disablecsssourcemap)
* [extraBabelPresets](#extrababelpresets)
* [extraBabelPlugins](#extrababelplugins)
* [extraBabelIncludes](#extrababelincludes)
C
chencheng 已提交
105 106 107 108
* [copy](#copy)
* [proxy](#proxy)
* [sass](#sass)
* [manifest](#manifest)
C
chencheng (云谦) 已提交
109
* [ignoreMomentLocale](#ignoremomentlocale)
C
chencheng 已提交
110
* [disableDynamicImport](#disabledynamicimport)
C
chencheng 已提交
111
* [env](#env)
S
😴  
sorrycc 已提交
112

C
chencheng 已提交
113
### entry
S
📖  
sorrycc 已提交
114

115 116
Specify webpack entries, support [glob](https://github.com/isaacs/node-glob) format.

P
plainnany 已提交
117
suppose your project is multipages, wanting files in src/pages as entries. you can do the followings.
118 119 120 121 122

```
"entry": "src/pages/*.js"
```

C
chencheng 已提交
123
### theme
C
chencheng (云谦) 已提交
124 125 126 127

Configure the theme, in fact, with less variables. Support both object and string type, the string needs to point to a file which return configurations.

e.g.
S
📖  
sorrycc 已提交
128 129

```
C
chencheng 已提交
130 131 132
"theme": {
  "@primary-color": "#1DA57A"
}
S
📖  
sorrycc 已提交
133 134
```

C
chencheng (云谦) 已提交
135
or,
S
📖  
sorrycc 已提交
136 137

```
C
chencheng 已提交
138
"theme": "./theme-config.js"
S
📖  
sorrycc 已提交
139 140
```

C
chencheng 已提交
141
### define
C
chencheng (云谦) 已提交
142 143 144 145

Pass to code through the webpack's DefinePlugin plugin, the value will automatically be processed with `JSON.stringify`.

e.g.
S
😴  
sorrycc 已提交
146

C
chencheng 已提交
147 148 149 150 151 152
```js
"define": {
  "process.env.TEST": 1,
  "USE_COMMA": 2,
}
```
S
🙃  
sorrycc 已提交
153

C
chencheng 已提交
154
### externals
C
chencheng (云谦) 已提交
155 156 157 158

Configure webpack's [externals] (https://webpack.js.org/configuration/externals/) property.

e.g.
S
🙃  
sorrycc 已提交
159

C
chencheng 已提交
160
```js
C
chencheng (云谦) 已提交
161
// Don't pack react and react-dom
C
chencheng 已提交
162 163 164 165 166
"externals": {
  "react": "window.React",
  "react-dom": "window.ReactDOM"
}
```
S
😴  
sorrycc 已提交
167

C
chencheng 已提交
168
### alias
C
chencheng (云谦) 已提交
169 170

Configure webpack's [resolve.alias](https://webpack.js.org/configuration/resolve/#resolve-alias) property.
S
😴  
sorrycc 已提交
171

D
dongge 已提交
172 173 174 175
### extraResolveExtensions

Configure webpack's [resolve.extensions](https://webpack.js.org/configuration/resolve/#resolve-extensions) property.

C
chencheng 已提交
176
### browserslist
C
chencheng (云谦) 已提交
177 178 179 180

Configure [browserslist](https://github.com/ai/browserslist), works on both babel-preset-env and autoprefixer.

e.g.
S
😴  
sorrycc 已提交
181

C
chencheng 已提交
182 183 184 185
```js
"browserslist": [
  "> 1%",
  "last 2 versions"
S
😴  
sorrycc 已提交
186 187 188
]
```

C
chencheng 已提交
189
### publicPath
C
chencheng (云谦) 已提交
190 191

Configure webpack's [output.publicPath](https://webpack.js.org/configuration/output/#output-publicpath) property.
S
📖  
sorrycc 已提交
192

C
chencheng 已提交
193
### outputPath
C
chencheng (云谦) 已提交
194 195

Configure webpack's [output.path](https://webpack.js.org/configuration/output/#output-path) property.
S
📖  
sorrycc 已提交
196

C
chencheng 已提交
197
### devtool
C
chencheng (云谦) 已提交
198 199

Configure webpack's [devtool](https://webpack.js.org/configuration/devtool/) property.
S
📖  
sorrycc 已提交
200

C
chencheng 已提交
201
### commons
C
chencheng (云谦) 已提交
202 203 204 205

Configure webpack's [CommonsChunkPlugin](https://webpack.js.org/plugins/commons-chunk-plugin/) plugin, the format is Array.

e.g.
S
📖  
sorrycc 已提交
206

C
chencheng 已提交
207 208 209 210 211 212 213 214 215 216 217 218 219
```markup
"commons": [
  {
    async: '__common',
    children: true,
    minChunks(module, count) {
      if (pageCount <= 2) {
        return count >= pageCount;
      }
      return count >= pageCount * 0.5;
    },
  },
]
S
📖  
sorrycc 已提交
220 221
```

222 223 224 225
### hash

Configuration to build with hash file name, and it's usually used in conjunction with the [manifest](#manifest).

C
chencheng 已提交
226 227 228 229 230 231 232 233 234 235 236 237
### html

Configure [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) plugin.

e.g.

```markup
"html": {
  "template": "./src/index.ejs"
}
```

C
chencheng 已提交
238
### disableCSSModules
C
chencheng (云谦) 已提交
239 240

Disable [CSS Modules](https://github.com/css-modules/css-modules),we do not recommend doing this.
S
😴  
sorrycc 已提交
241

C
chencheng 已提交
242
### disableCSSSourceMap
C
chencheng (云谦) 已提交
243 244

Disable generate CSS's SourceMap.
S
😴  
sorrycc 已提交
245

C
chencheng 已提交
246
### extraBabelPresets
C
chencheng (云谦) 已提交
247 248

Define an additional list of babel presets, the formatt is Array.
S
😴  
sorrycc 已提交
249

C
chencheng 已提交
250
### extraBabelPlugins
C
chencheng (云谦) 已提交
251 252

Define an additional list of babel plugins, the formatt is Array.
S
😴  
sorrycc 已提交
253

C
chencheng 已提交
254
### extraBabelIncludes
C
chencheng (云谦) 已提交
255 256

Define an additional list of file matches that need to be transformed with babel, the format is Array.
257

C
chencheng 已提交
258
### copy
C
chencheng (云谦) 已提交
259 260 261 262

Define a list of files that need to be copied. The format is an array, and the format of the item refers to the configuration of [copy-webpack-plugin] (https://github.com/webpack-contrib/copy-webpack-plugin).

e.g.
263

C
chencheng 已提交
264 265 266 267 268 269 270 271
```markup
"copy": [
  {
    "from": "",
    "to": ""
  }
]
```
272

S
😴  
sorrycc 已提交
273
### proxy
C
chencheng (云谦) 已提交
274 275 276 277

Configure the [proxy] (https://webpack.js.org/configuration/dev-server/#devserver-proxy) property of webpack-dev-server.

e.g. proxy requests to other servers,
S
😴  
sorrycc 已提交
278

C
chencheng 已提交
279
```markup
S
😴  
sorrycc 已提交
280 281 282 283 284 285 286 287 288
"proxy": {
  "/api": {
    "target": "http://jsonplaceholder.typicode.com/",
    "changeOrigin": true,
    "pathRewrite": { "^/api" : "" }
  }
}
```

C
chencheng (云谦) 已提交
289
Then visit `/ api / users` to access the data from [http://jsonplaceholder.typicode.com/users](http://jsonplaceholder.typicode.com/users].
S
sorrycc 已提交
290

C
chencheng 已提交
291
### sass
C
chencheng (云谦) 已提交
292 293

Configure the options for [node-sass] (https://github.com/sass/node-sass#options). Note: node-sass and sass-loader dependencies must be installed in the project directory when using sass.
L
ls 已提交
294

C
chencheng 已提交
295
### manifest
C
chencheng (云谦) 已提交
296

C
chencheng 已提交
297
Configure to generate manifest.json, it's option will pass to [https://www.npmjs.com/package/webpack-manifest-plugin](https://www.npmjs.com/package/webpack-manifest-plugin).
S
sorrycc 已提交
298

C
chencheng 已提交
299
e.g.
S
sorrycc 已提交
300

C
chencheng 已提交
301 302 303 304 305
```markup
"manifest": {
  "basePath": "/app/"
}
```
S
sorrycc 已提交
306

C
chencheng 已提交
307
### ignoreMomentLocale
C
chencheng (云谦) 已提交
308

C
chencheng 已提交
309
Ignore moment locale file, used to reduce the size.
S
sorrycc 已提交
310

C
chencheng 已提交
311 312
### disableDynamicImport

偏右 已提交
313
Disable `import ()` to load on demand, but bundle all the files in a single file, implement via [babel-plugin-dynamic-import-node-sync](https://github.com/seeden/babel-plugin-dynamic-import-node-sync).
C
chencheng 已提交
314

S
sorrycc 已提交
315
### env
C
chencheng (云谦) 已提交
316

C
chencheng 已提交
317
Set specific options for certain environment. `development` is for dev, and `production` is for build.
S
sorrycc 已提交
318

C
chencheng 已提交
319
e.g.
S
sorrycc 已提交
320

C
chencheng 已提交
321
```js
S
sorrycc 已提交
322 323 324 325 326 327 328 329
"extraBabelPlugins": ["transform-runtime"],
"env": {
  "development": {
    "extraBabelPlugins": ["dva-hmr"]
  }
}
```

C
chencheng (云谦) 已提交
330
Thus, extraBabelPlugins in development is `['transform-runtime', 'dva-hmr']`, and `['transform-runtime']` in production.
S
🤔  
sorrycc 已提交
331

C
chencheng 已提交
332
## Environment Variables
C
chencheng (云谦) 已提交
333

C
chencheng 已提交
334
You can temporarily configure some parameters for environment variables, including:
335

C
chencheng 已提交
336
* `PORT`, default 8000
337 338
* `HOST`, default localhost
* `ANALYZE`, whether to analyze the output bundle in `roadhog build`
339 340 341 342
* `ESLINT`, set `none` disable eslint check
* `TSLINT`, set `none` disable tslint check
* `COMPRESS`, set `none` to disable file compressing in `roadhog build`
* `BROWSER`, set `none` to disable browser open in `roadhog dev`
343

C
chencheng 已提交
344
e.g. start dev server with port 3000,
S
🛌  
sorrycc 已提交
345 346

```bash
S
sorrycc 已提交
347
# OS X, Linux
C
chencheng 已提交
348
$ PORT=3000 roadhog dev
S
😋  
sorrycc 已提交
349

S
sorrycc 已提交
350
# Windows (cmd.exe)
C
chencheng 已提交
351
$ set PORT=3000&&roadhog dev
S
sorrycc 已提交
352 353

# Or use cross-env for all platforms
C
chencheng 已提交
354
$ cross-env PORT=3000 roadhog dev
S
🤔  
sorrycc 已提交
355 356
```

S
add faq  
sorrycc 已提交
357
## FAQ
C
chencheng (云谦) 已提交
358

C
chencheng 已提交
359
### Why is it called roadhog ?
S
add faq  
sorrycc 已提交
360

C
chencheng 已提交
361
roadhog is a hero from overwatch, just like [dva](https://github.com/dvajs/dva).
S
add faq  
sorrycc 已提交
362

C
chencheng (云谦) 已提交
363
<img src="https://gw.alipayobjects.com/zos/rmsportal/nnuuSFhDFUOfvYSRyvBh.png" width="405" height="411" />
S
🤑  
sorrycc 已提交
364

S
😋  
sorrycc 已提交
365
## LICENSE
C
chencheng (云谦) 已提交
366

S
😋  
sorrycc 已提交
367
MIT