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.

    Install

    npm i webpack-boiler

    DownloadsWeekly Downloads

    80

    Version

    0.5.0

    License

    MIT

    Unpacked Size

    30 kB

    Total Files

    4

    Last publish

    Collaborators

    • wyattades