1 | # Gnoll :japanese_ogre:
|
2 |
|
3 | Tool for fast and easy bootstraping Webpack & React projects.
|
4 | It can perform basic tasks without any configuration files.
|
5 | But if you need to change some settings, you can create config files
|
6 | in the your project and extend the default configuration.
|
7 |
|
8 | ## Table of content
|
9 |
|
10 | - [Install](#install)
|
11 | - [Commands](#commands)
|
12 | - [Configuration](#configuration)
|
13 | - [License](#license)
|
14 |
|
15 | ## Install
|
16 |
|
17 | ```
|
18 | npm install gnoll
|
19 | ```
|
20 |
|
21 | Gnoll has command line interface.
|
22 | You can add commands to the `package.json` file:
|
23 |
|
24 | ```json
|
25 | {
|
26 | "scripts": {
|
27 | "start": "gnoll start",
|
28 | "build": "gnoll build"
|
29 | }
|
30 | }
|
31 | ```
|
32 |
|
33 | ## Commands
|
34 |
|
35 | ### gnoll build
|
36 |
|
37 | Creates optimized production build.
|
38 |
|
39 | #### Options
|
40 |
|
41 | - `-e, --entry path`
|
42 | <br>
|
43 | Default: `./src/index.js`
|
44 | <br>
|
45 | Webpack entry file.
|
46 |
|
47 | - `-o, --out path`
|
48 | <br>
|
49 | Default: `./build`
|
50 | <br>
|
51 | Path to the output directory.
|
52 |
|
53 | - `--html path/to/index.html`
|
54 | <br>
|
55 | Default: `./src/index.html` (if exists)
|
56 | <br>
|
57 | Page that will be bundled with automatically injected assets
|
58 | using `html-webpack-plugin`.
|
59 | <br>
|
60 | If you want to explicitly disable building html, use option `--no-html`.
|
61 |
|
62 | - `--config path/to/webpack.config.js`
|
63 | <br>
|
64 | This option allows to provide path to the custom webpack config file.
|
65 |
|
66 | - `--env=development|production`
|
67 | <br>
|
68 | Default: `production`
|
69 | <br>
|
70 | Value of the `NODE_ENV` environment variable.
|
71 |
|
72 | - `--target=web|node`
|
73 | <br>
|
74 | Default: `web`
|
75 | <br>
|
76 | This options allows to specify target platform.
|
77 | - `babel-preset-env` transpiles for node target
|
78 | - sets webpack:
|
79 | libraryTarget commonjs
|
80 | target: node
|
81 |
|
82 | - `--assets-caching`
|
83 | <br>
|
84 | This option enables optimizations for long term caching of static assets.
|
85 | <br>
|
86 | Optimizations are based on this guide from webpack documentation –
|
87 | https://webpack.js.org/guides/caching/
|
88 | - It inserts hash of file content in its filename.
|
89 | This allows to cache files forever, because changed files will always have
|
90 | different names.
|
91 | - Generates `manifest.json` file that maps original filenames to hashed
|
92 | ones.
|
93 |
|
94 | ### gnoll watch
|
95 |
|
96 | Creates development build and rebuild on changes.
|
97 | <br>
|
98 | This command has same options as `build`, but
|
99 | default value for the `--env` option is `development`
|
100 |
|
101 | ### gnoll start
|
102 |
|
103 | Starts webpack development server.
|
104 | <br>
|
105 | This command has the same options as `build` except for
|
106 | `--env` (it always is set to `development`) and `--target` (always is `web`)
|
107 |
|
108 | ### gnoll lib
|
109 |
|
110 | Use this command if you want to build library that should provide modules.
|
111 | <br>
|
112 | When building library, js files are compiled by Babel.
|
113 | Format of the modules is changed to CommonJS.
|
114 | All other files are copied as is. Result is placed in the `lib` directory.
|
115 |
|
116 | **Options:**
|
117 |
|
118 | `--target=web|node`
|
119 |
|
120 | `-e, --entry`
|
121 | <br>
|
122 | Default: `./src`
|
123 |
|
124 | `-o, --out`
|
125 | <br>
|
126 | Default: `./lib`
|
127 |
|
128 | `--watch`
|
129 | <br>
|
130 | Starts watcher that recompiles files on changes.
|
131 |
|
132 | `--source-maps`
|
133 | <br>
|
134 | Embed inline source maps into compiled files.
|
135 |
|
136 | ## Configuration
|
137 |
|
138 | This section describes how you can change configuration.
|
139 |
|
140 | ### Webpack
|
141 |
|
142 | Default webpack config includes following loaders:
|
143 |
|
144 | - `babel-loader` for `js` and `jsx` files
|
145 | - `file-loader` for the following formats:
|
146 | - images: `png` `svg` `jpg` `jpeg` `gif` `webp`
|
147 | - fonts: `eot` `ttf` `woff` `woff2`
|
148 | - media: `mp4` `ogg` `webm` `mp3`
|
149 |
|
150 | Building styles is not included in gnoll by default, but you can add it with
|
151 | [gnoll-scss](https://github.com/sunflowerdeath/gnoll/tree/master/packages/gnoll-scss) plugin.
|
152 |
|
153 | If you want to change something in the webpack config, you can create
|
154 | `webpack.config.js` in your project and extend the default config.
|
155 | For convenience, you can use
|
156 | [webpack-merge](https://github.com/survivejs/webpack-merge)
|
157 | for merging several webpack configs.
|
158 |
|
159 | ```js
|
160 | const merge = require('webpack-merge')
|
161 | const baseConfig = require('gnoll/config/webpack')
|
162 |
|
163 | module.exports = merge(baseConfig, {
|
164 | plugins [
|
165 | somePlugin
|
166 | ],
|
167 | module: {
|
168 | rules: [
|
169 | { test: /\.smth$/, loader: 'some-loader' }
|
170 | ]
|
171 | }
|
172 | }
|
173 | ```
|
174 |
|
175 | #### Extracting vendor and runtime chunks
|
176 |
|
177 | _TODO_
|
178 |
|
179 | ### Babel
|
180 |
|
181 | Javascript is compiled with Babel.
|
182 | Default config uses following presets:
|
183 | - `babel-preset-env` (ES6 syntax features)
|
184 | - `babel-preset-react` (JSX syntax)
|
185 | - `babel-preset-stage-0` (Unfinished proposals to the ES standard)
|
186 |
|
187 | If you want to change change babel config, you can create `.babelrc` or
|
188 | `babel.config.js` file in the your project or set `babel` property
|
189 | in the `package.json`.
|
190 |
|
191 | For example, this is how you can add support for decorators:
|
192 | ```js
|
193 | // babel.config.js
|
194 | const baseConfig = require('gnoll/config/babel')
|
195 |
|
196 | module.exports = {
|
197 | ...baseConfig,
|
198 | plugins: [
|
199 | ['@babel/plugin-proposal-class-properties', { loose: true }],
|
200 | '@babel/plugin-proposal-decorators',
|
201 | ]
|
202 | }
|
203 | ```
|
204 |
|
205 | ### Browsers
|
206 |
|
207 | _TODO_
|
208 |
|
209 | ### Env vars
|
210 |
|
211 | ```
|
212 | NODE_ENV
|
213 | GNOLL_TARGET
|
214 | GNOLL_ASSETS_CACHING
|
215 | GNOLL_DEV_SERVER
|
216 | GNOLL_LIB
|
217 | ```
|
218 |
|
219 | ## License
|
220 |
|
221 | Public domain, see the LICENCE file.
|