Webpack Boiler[plate]
Opinionated Webpack configuration boilerplate. Great for easily configuring React or vanilla Progressive Web Apps.
Features
- Babel
- React
- Typescript
- Hot Reloading (with react-hot-loader)
- Sass and SCSS
- Web App Manifest and service worker
- Web workers
- Minified JS, CSS, & HTML
- Cross-browser compatability with browserlist
- HTML templates (Jade / Pug)
Install
npm install --save-dev webpack-boiler
# If you want to use React:
npm install --save react react-dom react-hot-loaderUsage
In your project root, create the file webpack.config.js containing:
module.exports = require('webpack-boiler')({
react: true,
pages: [
{
title: 'Hello World!',
},
],
});This defines a webpack configuration with default entry point: <project_root>/src/index.js
(NOTE: Only source files in the src directory will be read!)
To develop and bundle your app, add the following commands to your package.json's scripts:
- Development (your project will hot-reload at http://localhost:8080):
"dev": "cross-env NODE_ENV=development webpack serve"-
Production Build (your project will build to the
./distdirectory):
"build": "cross-env NODE_ENV=production webpack"You can also view a simple example here.
API
webpackBoiler([config])
Returns: Object - webpackConfigObject
var webpackBoiler = require('webpack-boiler');
var webpackConfigObject = webpackBoiler({
/* config */
});Config Object
All config parameters are optional
| Name | Type | Default | Description |
|---|---|---|---|
| react | boolean |
false |
Enable React parsing with Babel (must install react-hot-loader) |
| entry | Object |
{} |
Webpack entry points. Adds property index: '<project_root>/src/index.js' if you don't provide any entries |
| output | string |
dist |
Build directory |
| env | Object |
{} |
Variables passed to source code in process.env
|
| googleAnalytics | string |
Google Analytics ID | |
| basename | string |
Basename of website. This is helpful for GithubPages websites e.g. webpack-boiler for wyattades.github.io/webpack-boiler
|
|
| url | string |
Passed to process.env as URL (is set to http://localhost:<devPort> during development) |
|
| devPort | number |
8080 |
Development port number |
| manifest | Object |
null |
Web App manifest config (if it's an object, then provides defaults for description, name, icons, start_url, and lang based on other config values) |
| offline | boolean |
false |
Offline cache your bundle assets. Defaults to true if manifest is provided. You can also provide an Object for custom offline-plugin options |
| pages | Object[] |
[{}] |
Array of html page config objects (defaults to a single index.html file) |
| pages[].filename | string |
'index.html' |
Output filename |
| pages[].title | string |
Title of page | |
| pages[].meta | Object |
{} |
Inject meta-tags e.g. { description: 'wow!' }
|
| pages[].chunks | string[] |
['index'] |
Webpack chunks to include. Corresponds to the keys in entry
|
| pages[].favicon | string |
Path to favicon.ico | |
| pages[].lang | string |
'en-US' |
HTML language |
| pages[].appMountId | string |
'root' |
React root element ID. Only enabled if react=true
|
| pages[].cache | boolean |
true |
Set to false to disable page caching |
| pages[].mobile | boolean |
true |
Set to false to disable mobile viewport |
| pages[].template | string |
Relative path to custom pug template | |
| pages[].headElements | Object[] |
[] |
Append extra elements to <head> with an array of element attributes, where tag is the element's tag e.g. [{ tag: 'link', rel: 'stylesheet', href: 'style.css' }]
|
| pages[].bodyElements | Object[] |
[] |
Same as headElements but appended to the end of <body>
|
Manifest
To truly create a Progressive Web App, you need to provide an object to the manifest config parameter. This will produce a manifest.json file as well as a service worker
(sw.js) that caches the files on your website (using offline-plugin).
Custom Templates
Set the relative path to a custom pug template in the template config parameter. I recommend to structure the custom template like so:
example_template.pug
// Extend our `pug` template (Path may differ depending on example_template.pug's location)
extends ./node_modules/webpack-boiler/template.pug
// Put your content in a `block` with the name 'page_content'
block page_content
h1 Here's the custom content!
<p>You can write in the Jade/Pug style or in HTML</p>Cross-browser compatability
Javascript and CSS cross-browser compatability is determined by browserlist and executed by @babel/preset-env and postcss-preset-env respectively. Browserlist provides sensible defaults but you can refer to their docs for customization options.
Web Workers
Create Web Workers using the worker-loader plugin.
A worker is any source file ending in .worker.js or imported using worker-loader.
Example:
import Foo from './Foo.worker.js';
// or
import Bar from 'worker-loader!./Bar.js';Default (Opinionated) Behaviors
- Source files must be in a directory named
src - Importing CSS into your source code results in an extracted
.cssfile (using mini-css-extract-plugin) - CSS and JS bundle filenames are appended with the hash of that file e.g.
index.0435m918429fjsaa832l.js - Files in
<project_root>/publicare automatically copied to the bundle output (and retain their folder structure) - Images imported in your source code are placed in an
assetsdirectory in your bundle - I suggest providing a
.icoor.pngfavicon file with size 192x192 (you can include additional sizes in the.icofile)
DISCLAIMER
This package is still in development and is constantly changing. Please report discrepencies to Github issues.