1 | # Gnoll :japanese_ogre:
|
2 |
|
3 | Tool for fast and easy bootstraping Webpack & React projects.
|
4 |
|
5 | - It can build code in production and development modes,
|
6 | and perform other tasks like linting and formatting.
|
7 | - It includes all required dependencies, so you don't need to install them manually.
|
8 | - It contains default configuration, but if you need to change some settings,
|
9 | you can override them in your project.
|
10 |
|
11 | ## Install
|
12 |
|
13 | ```
|
14 | npm install gnoll
|
15 | ```
|
16 |
|
17 | ## Commands
|
18 |
|
19 | Gnoll has command line interface. You can add commands to your `package.json` file:
|
20 |
|
21 | ```json
|
22 | {
|
23 | "scripts": {
|
24 | "start": "gnoll start",
|
25 | "build": "gnoll build",
|
26 | "lint": "gnoll lint"
|
27 | }
|
28 | }
|
29 | ```
|
30 |
|
31 | ### build [--config path] \[--caching]
|
32 |
|
33 | Creates optimized production build.
|
34 |
|
35 | It builds entry `src/index.js` and outputs results to `dist` dir.
|
36 | You can read in next section what is included in default config.
|
37 | <br>
|
38 | If you want to change something, for example, add plugins or loaders,
|
39 | you can extend default config by creating `webpack.config.js` in your project.
|
40 |
|
41 | ```js
|
42 | // webpack.config.js
|
43 |
|
44 | // default config
|
45 | let config = require('gnoll/config/webpack')
|
46 |
|
47 | // add plugin
|
48 | config.plugins.push(plugin)
|
49 |
|
50 | // add loader
|
51 | config.module.rules.push({
|
52 | test: /\.smth$/,
|
53 | loader: 'some-loader'
|
54 | })
|
55 |
|
56 | module.exports = config
|
57 | ```
|
58 |
|
59 | **`--config path`**
|
60 | <br>
|
61 | This option allows to provide path to different webpack config file.
|
62 |
|
63 | **`--caching`**
|
64 | <br>
|
65 | This option optimizes build for long term caching of static assets.
|
66 | <br>
|
67 | Optimizations are based on this guide from webpack documentation -
|
68 | https://webpack.js.org/guides/caching/
|
69 |
|
70 | - It includes hash of file content in its filename.
|
71 | This allows to cache files forever, because changed files will always have different names.
|
72 | - Extracts webpack runtime into separate entry chunk `runtime`, because it can change on rebuild.
|
73 | - Generates `manifest.json` file that maps original filenames to hashed ones.
|
74 |
|
75 | Also, it is common practice to separate some vendor modules to separate bundle.
|
76 | You can do it by extending webpack config file in your project like this:
|
77 |
|
78 | ```js
|
79 | config.entry = {
|
80 | main: './src/index.js',
|
81 | vendor: ['react', 'react-dom']
|
82 | }
|
83 |
|
84 | // Note that the plugin is added to the beginning.
|
85 | // It is important to insert it before CommonsChunkPlugin that extracts 'runtime'
|
86 | config.plugins.unshift(new webpack.optimize.CommonsChunkPlugin({
|
87 | name: 'vendor',
|
88 | minChunks: Infinity
|
89 | }))
|
90 | ```
|
91 |
|
92 | ### watch [--config path]
|
93 |
|
94 | Creates development build and rebuild on changes.
|
95 |
|
96 | ### start [--config path]
|
97 |
|
98 | Starts webpack development server.
|
99 |
|
100 | If you have file `src/index.html` in your project, it will be included
|
101 | using `html-webpack-plugin` and served on dev-server with automatically injected assets.
|
102 |
|
103 | ### lib [--watch] [--source-maps]
|
104 |
|
105 | Use this command if you want to build library that should provide modules.
|
106 | <br>
|
107 | When building library, js files are compiled by Babel.
|
108 | Format of the modules is changed to CommonJS.
|
109 | All other files are copied as is. Result is placed in the `lib` directory.
|
110 |
|
111 | **`--watch`**
|
112 | <br>
|
113 | Starts watcher that recompiles files on changes.
|
114 |
|
115 | **`--source-maps`**
|
116 | <br>
|
117 | Embed inline source maps into compiled files.
|
118 |
|
119 | ### lint
|
120 |
|
121 | Checks source code with [ESLint](https://eslint.org).
|
122 |
|
123 | Default config is based on `eslint-config-airbnb` with addition of `eslint-config-prettier`,
|
124 | which removes all rules related to formatting and replaces them with rule
|
125 | that gives error when source code doesn't match autoformatted output from the Prettier.
|
126 |
|
127 | If you need to integrate linting with your IDE or editor plugin, you should
|
128 | create `.eslintrc.js` file in your project and extend the default config like this:
|
129 |
|
130 | ```js
|
131 | // .eslintrc.js
|
132 | module.exports = {
|
133 | extends: [
|
134 | './node_modules/gnoll/config/eslint.js'
|
135 | ]
|
136 | }
|
137 | ```
|
138 |
|
139 | Also, you can override any ESLint settings in this file, if you want.
|
140 |
|
141 | If you want to change Prettier settings, you can create `.prettierrc` (JSON format)
|
142 | or `prettier.config.js` (JS module) in your project.
|
143 |
|
144 | ## Included loaders
|
145 |
|
146 | ### Javascript
|
147 |
|
148 | Javascript is compiled using Babel.
|
149 | <br>
|
150 | In addition to ES6 syntax features, it also supports:
|
151 |
|
152 | - Unfinished proposals to the ES standard
|
153 | ([`babel-preset-stage-0`](https://babeljs.io/docs/plugins/preset-stage-0/))
|
154 | - JSX syntax
|
155 | - Decorators ([`babel-plugin-transform-decorators-legacy`](
|
156 | https://github.com/loganfsmyth/babel-plugin-transform-decorators-legacy))
|
157 |
|
158 | When building for production code is minified by UglifyJS.
|
159 |
|
160 | ### Static files
|
161 |
|
162 | These formats are built using `file-loader`:
|
163 |
|
164 | - images: `png` `svg` `jpg` `jpeg` `gif` `webp`
|
165 | - fonts: `eot` `ttf` `woff` `woff2`
|
166 | - media: `mp4` `ogg` `webm` `mp3`
|