1 | [![Build Status](https://travis-ci.org/rei/febs.svg?branch=master)](https://travis-ci.org/rei/febs)
|
2 |
|
3 | # FEBS
|
4 |
|
5 | ## Summary
|
6 |
|
7 | `FEBS` is an extensible [webpack](https://webpack.js.org/)\-based [front-end build system](https://engineering.rei.com/frontend/the-rei-front-end-build-system.html)
|
8 | designed to be used by a community of front-end developers or a series of projects using a similar set of technologies
|
9 | in order to reduce duplicate effort of build configurations.
|
10 |
|
11 | Its code falls into two categories:
|
12 |
|
13 | ### [Build Features](#build-features)
|
14 |
|
15 | * [JavaScript](#javascript)
|
16 | * [Style](#style)
|
17 | * [Source Maps](#source-maps)
|
18 | * [Live reloading](#live-reloading)
|
19 | * [Code Watching](#code-watching)
|
20 |
|
21 | ### [FEBS core](#febs-core)
|
22 |
|
23 | - [Command-line interface](#command-line-interface)
|
24 | - [Development and production builds](#production-and-development-builds)
|
25 | - Produces a [Build Manifest](#build-manifest) so you can insert assets on your page using an [Asset Injector](#asset-injector)
|
26 |
|
27 | Learn more about [REI's Front-End Build System ](https://engineering.rei.com/frontend/the-rei-front-end-build-system.html)
|
28 | by checking out the introductory post on the [REI Co-op Engineering blog](https://engineering.rei.com).
|
29 |
|
30 | ## Getting Started
|
31 |
|
32 | ### Prerequisites
|
33 | Confirm that you satisfy the [minimum node.js version](https://github.com/rei/febs/blob/master/package.json#L32).
|
34 |
|
35 | ### Install
|
36 |
|
37 | #### Install the dependency
|
38 |
|
39 | `npm install --save @rei/febs core-js@^3.1.x`
|
40 |
|
41 | #### Assign build tasks
|
42 |
|
43 | FEBS exposes an executable named `febs` to be used within the scripts of your `package.json`, e.g:
|
44 |
|
45 | "scripts": {
|
46 | "build": "febs prod",
|
47 | "dev": "febs dev --no-dev-server",
|
48 | "live-reload": "febs dev"
|
49 | "watch": "febs dev --no-dev-server --watch"
|
50 | }
|
51 |
|
52 | #### Update or use [defaults](#default-configuration) to specify paths for the CSS and JS you want to compile and [run](#run)
|
53 |
|
54 | See [Command-line Interface](#command-line-interface) for more details and additional ways to run.
|
55 |
|
56 | ## Default Configuration
|
57 |
|
58 | ### Entry points
|
59 | - Default JavaScript entry point: `/src/js/entry.js`
|
60 | - Default Style entry point: `/src/style/entry.less`
|
61 |
|
62 | ### Output path
|
63 | - Bundles written to: `/dist/<packageName>/`.
|
64 |
|
65 | Given the above defaults, FEBS will generate two bundles at the following paths:
|
66 |
|
67 | ./dist/<packageName>/app.1234.js
|
68 | ./dist/<packageName>/app.1234.css
|
69 |
|
70 | You can adjust these default configurations using the [febs configuration](#febs-configuration)
|
71 |
|
72 | ## Build Features
|
73 |
|
74 | ### JavaScript
|
75 | - Supports [Vue](https://vuejs.org/) [single file components](https://vuejs.org/v2/guide/single-file-components.html).
|
76 | - Transpiles latest JavaScript via [@babel/preset-env](https://babeljs.io/docs/en/babel-preset-env)
|
77 | - Automatically polyfills based on usage and [targeted browsers](https://github.com/rei/febs/blob/babel-polyfills/webpack-config/webpack.base.conf.js#L96).
|
78 |
|
79 | ### Style
|
80 | - [Less](http://lesscss.org/) - [deprecated](#deprecation)
|
81 | - [Sass/SCSS](https://sass-lang.com/)
|
82 | - [PostCSS](https://github.com/postcss)
|
83 |
|
84 | ### Source Maps
|
85 | Source maps are generated for your bundles via the following [`webpack` methods](https://webpack.js.org/configuration/devtool/):
|
86 |
|
87 | * dev: `eval-source-map`
|
88 | * prod: `source-map`
|
89 |
|
90 | ### Linting
|
91 | As FEBS is responsible only for *building* your code, it does not provide for linting. You should
|
92 | implement a linting step per your style guide as a separate npm task in your `package.json`.
|
93 |
|
94 | ### Code watching
|
95 | To enable code watching, run:
|
96 |
|
97 | febs dev --no-dev-server --watch
|
98 |
|
99 | ### Live reloading
|
100 | @TODO: additional detail
|
101 |
|
102 | ## FEBS Core
|
103 |
|
104 | ### Command-line interface
|
105 | FEBS provides a simple command-line interface.
|
106 |
|
107 | ### Production and Development Builds
|
108 |
|
109 | #### Production Build Task
|
110 |
|
111 | febs prod
|
112 |
|
113 | #### Development Build Task
|
114 |
|
115 | febs dev
|
116 | febs dev -no-dev-server
|
117 | febs dev --no-dev-server --watch
|
118 |
|
119 | ### FEBS Configuration
|
120 |
|
121 | If the default entry/output paths don't work for you, you can specify them by using a `febs-config.json` file next to your package.json that is using `febs`.
|
122 |
|
123 | Here is an example of `entry`/`output` paths using a typical `Java`/`Maven`-like project directory structure.
|
124 |
|
125 | *`febs-config.json`*
|
126 |
|
127 | {
|
128 | "entry": {
|
129 | "details": [
|
130 | "src/main/js/pages/details/entry.js"
|
131 | ],
|
132 | "details-reviews": [
|
133 | "src/main/js/pages/details/reviews.js"
|
134 | "src/main/js/pages/details/write-review.js"
|
135 | ]
|
136 | }
|
137 | "output": {
|
138 | "path": "./target/classes/dist"
|
139 | },
|
140 | "ssr": true
|
141 | }
|
142 |
|
143 | Notes:
|
144 | - the `febs-config.json` overrides the `webpack.overrides.config.js` file. (i.e., if `entry` and `output` are specified in both, the build will use the entries in `febs-config.json`.
|
145 | - the `entry/output` paths are resolved relative to npm root.
|
146 | - the `output` path is appended with `<package name>`, i.e., `dist/details/`. Use the overrides file if you want to specify a unique path.
|
147 | #### `entry` property
|
148 |
|
149 | In the `febs-config.json` example above, we are creating our own entry points instead of using the
|
150 | [defaults](#default-configuration). We specify the path where our JavaScript and styles live.
|
151 |
|
152 | Note: The `entry` paths are specified relative to npm root directory.
|
153 |
|
154 | #### `output` property
|
155 |
|
156 | In the `febs-config.json` example above we change the default output path to the Java classpath where a Java asset injector will be able to read for injection.
|
157 |
|
158 | Notes:
|
159 | - The `output` paths are specified relative to npm root directory.
|
160 | - the `output` path is appended with `<package name>`, i.e., `dist/<package name>/`. Use the overrides file if you want to specify a unique path.
|
161 |
|
162 | #### `ssr` property
|
163 |
|
164 | This value determines whether or not to build the `vue-ssr-server-bundle.json` required
|
165 | for server-side rendering.
|
166 |
|
167 | Notes:
|
168 | - Enabling this will add additional time to the build as it essentially needs to run 2 builds, one
|
169 | for the client and one for the server. Additionally, the generated `vue-ssr-server-bundle.json` is very large.
|
170 | - This is automatically disabled during development builds, i.e., `febs dev`.
|
171 |
|
172 | #### Example configuration output
|
173 | Given the above example, FEBS will generate two bundles at the following paths:
|
174 |
|
175 | ./target/classes/dist/<package name>/details.1234.js
|
176 | ./target/classes/dist/<package name>/detail-reviews.1234.js
|
177 |
|
178 | - `details.1234.js` will only contain JavaScript contained in entry.js (including its dependencies)
|
179 |
|
180 | - `details-reviews.1234.js` will bundle reviews.js and write-review.js files into one bundle
|
181 |
|
182 | If you'd like to further configure FEBS, you can look at the [webpack overrides](#webpack-overrides)
|
183 |
|
184 | ### Webpack overrides
|
185 |
|
186 | You may also configure additional loaders and update your `input/output` entries in a local file
|
187 | called `webpack.overrides.conf.js` (See below example).
|
188 |
|
189 | If you do need an override, consider opening a PR to get this pulled into the
|
190 | base config or reach out to [support](#support). By doing so, we can all benefit from your overrides and prevent others from needing to duplicate the same overrides.
|
191 |
|
192 | // Webpack.overrides.conf.js
|
193 | module.exports = {
|
194 | .
|
195 | .
|
196 | module: {
|
197 | rules: [{
|
198 | test: '/\.js$/'
|
199 | use: {
|
200 | loader: 'cool-js-loader'
|
201 | }
|
202 | }]
|
203 | },
|
204 | .
|
205 | .
|
206 | plugins: [
|
207 | new CoolPlugin()
|
208 | ]
|
209 | };
|
210 |
|
211 | You can find out all of the Webpack defaults by reviewing the [base webpack config](https://github.com/rei/front-end-build-configs/blob/master/application/microsite/webpack.base.conf.js).
|
212 |
|
213 | ## Additional Concepts
|
214 |
|
215 | ### Build Manifest
|
216 |
|
217 | A `febs-manifest.json` is built to the output directory. This is a
|
218 | mechanism to be used by an asset injector to insert assets onto a page.
|
219 |
|
220 | @TODO: Additional detail
|
221 |
|
222 | ### Asset Injector
|
223 |
|
224 | An asset injector uses a [febs-manifest.json](#build-manifest) to insert production
|
225 | assets into the markup of a webpage.
|
226 |
|
227 | See our example JavaScript implementation of the an asset injector. One could
|
228 | create one to be used by Thymeleaf, Freemarker, JSP Tags, Vue, React, Mustache, Handlebars, etc.
|
229 |
|
230 | @TODO: publish JavaScript implementation and asset pipeline architectural
|
231 | diagrams and relate to an "asset pipeline".
|
232 |
|
233 | ## Project Information
|
234 |
|
235 | ### Release management
|
236 |
|
237 | The project strictly use [semver](https://semver.org/).
|
238 |
|
239 | The main thing to call out here is that if maintainers (intentionally) introduce
|
240 | an incompatible Webpack configuration change, the major version is bumped. When
|
241 | the project moves from Webpack 3 to 4, the major version is bumped.
|
242 |
|
243 | If the project unintentionally introduces a new bug through a change through
|
244 | febs core or build features, there will be a prompt fix. Additionally, maintainers
|
245 | will continue to improve our unit and functional testing strategies and bug
|
246 | response times.
|
247 |
|
248 | Somewhat related, the intention is to move the Webpack configuration to a separate
|
249 | repository and have that be configurable. At that point the project can have more
|
250 | fine-grained release management and flexibility as well as allow non-internal
|
251 | customers to have complete control over their shared base configuration.
|
252 |
|
253 | ### Deprecation
|
254 |
|
255 | When something gets deprecated, it will not be supported in the next major
|
256 | release but will continue to get [supported](#support) for the previous version.
|
257 |
|
258 | ### Support
|
259 |
|
260 | The project focus is around FEBS core. For [Build Features](#build-features)
|
261 | it should be look at as community of practice effort, this is one of the main ideas.
|
262 | However, a maintainer should be a major contributor to features.
|
263 |
|
264 | *For our internal customers:* Think of FEBS as just a base Webpack
|
265 | config that you can edit that happens to be in a different repository
|
266 |
|
267 | Maintainers support one major version behind and attempt to minimize and group
|
268 | up major version releases to reduce upgrade/support burden.
|
269 |
|
270 | #### Internal open source customers
|
271 |
|
272 | We fully support our internal customers. That means we will respond to Slack
|
273 | messages and help troubleshoot issues, feature requests, etc.
|
274 |
|
275 | Feel free to swing by or hit us up on Slack in the #febs-users channel or just file
|
276 | an issue here :)
|
277 |
|
278 | #### External open source customers
|
279 |
|
280 | Maintainers will respond to Github issues within a week for issues with FEBS core.
|
281 | Unfortunately, there are no guarantees for "immediate" support due to bandwidth.
|
282 | However, we are happy to collaborate and work together on pull requests. You are
|
283 | very much welcome and encouraged to fork this project and see where it goes.
|
284 |
|
285 | Also, we'd love to hear your ideas and feedback on different approaches or similar
|
286 | solutions in the community that you think could improve FEBS.
|