webpack-boiler

v0.5.0

Published

2 years ago

Babel, React, and HTML webpack config

Downloads

0High
0Medium
0Low

wyattades

webpack boiler boilerplate babel react typescript hot pug pwa offline worker

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

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 ./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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme