webpack-boiler

0.5.0 • Public • Published

Webpack Boiler[plate]

Opinionated Webpack configuration boilerplate. Great for easily configuring React or vanilla Progressive Web Apps.

npm

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-loader

Usage

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:

"dev": "cross-env NODE_ENV=development webpack serve"
  • Production Build (your project will build to the ./dist directory):
"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 .css file (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>/public are automatically copied to the bundle output (and retain their folder structure)
  • Images imported in your source code are placed in an assets directory in your bundle
  • I suggest providing a .ico or .png favicon file with size 192x192 (you can include additional sizes in the .ico file)

DISCLAIMER

This package is still in development and is constantly changing. Please report discrepencies to Github issues.

Versions

Current Tags

  • Version
    Downloads (Last 7 Days)
    • Tag
  • 0.5.0
    1
    • latest

Version History

Package Sidebar

Install

npm i webpack-boiler

Weekly Downloads

1

Version

0.5.0

License

MIT

Unpacked Size

30 kB

Total Files

4

Last publish

Collaborators

  • wyattades