Batch Craft Webpack

A zero config Webpack package made for Craft CMS
Explore the docs »

Report Bug · Request Feature

Table of Contents

• About the Project
  • Made For
  • Features
• Getting Started
  • Prerequisites
  • Installation
• Usage
• Roadmap
• Contributing
• License
• Contact
• Acknowledgements

About The Project

This package provides a quick and easy way to get setup with a fully featured Webpack setup.

We've tailored this package to our own requirements based on developing a multitude of Craft CMS projects ranging from simple to complex. It was originally based on the fine work by nystudio107 and refined into this package.

Made For

• Craft CMS (with Twigpack)
• VueJS

Features

• Webpack 4
• Core JS 3
• Vue Loader
• Post CSS
• Manifest Configuration for use with Twigpack
• State Preserving Hot Reload
• Build and Development Pipelines
• Source Maps
• Modern/Legacy Builds using Browserlist
• Compression
• ESLint
• Prettier

Getting Started

To get a local copy up and running follow these simple steps.

Installation

1. Install the package

npm install @batch/craft-webpack -D

2. Add the build scripts to your project's package.json

  "scripts": {
    "dev": "webpack-dev-server --progress --hide-modules --config=node_modules/@batch/craft-webpack/webpack.dev.js",
    "build": "export NODE_ENV=production && webpack --progress --hide-modules --config=node_modules/@batch/craft-webpack/webpack.prod.js",
    "dev-legacy": "webpack-dev-server --progress --hide-modules --config=node_modules/@batch/craft-webpack/webpack.dev.js --env.BUILD_TYPE=legacy",
    "dev-combined": "webpack-dev-server --progress --hide-modules --config=node_modules/@batch/craft-webpack/webpack.dev.js --env.BUILD_TYPE=combined"
  }

Usage

This package provides two pipelines out of the box, one for development and one for production builds.

Development builds default to using the modern config and will only output transpiled JS based on the modernBrowsers browserlist config defined in package.json. To test in legacy browers (e.g. IE11) you can use the legacy config (see below) which uses the legacyBrowsers browserlist config. A third mode, combined, will serve modern and legacy build artifacts.

Development

Runs the development pipeline. It'll create a local webserver using webpack-dev-server to serve the assets.

npm run dev

If you want to use the legacy or combined build types during development, you use the dev-legacy or dev-combined tasks

Production

Runs the production pipeline. This will compress the build artifacts ready for sites in production.

npm run build

Configuration

Settings

The settings in webpack.settings.js can be overridden at a project level by placing a webpack.settings.js file in the project root. This will be merged with the base webpack.settings.js file during build.

eg.

module.exports = {
    paths: {
        src: {
            base: "./resources/",
            css: "./resources/css/",
            js: "./resources/js/"
        }
    }
};

Webpack Config

Any custom Webpack config can be included by adding a webpack.config.js in the project root. This will be merged with the final Webpack config during build.

eg.

const path = require("path");

module.exports = {
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "src/vue/")
    }
  }
};

ESLint Config

The base ESLint config is setup with the following:

• airbnb/base
• vue/recommended
• prettier/recommended

By default, ESLint will lint *.js, *.vue files in the src directory. To change any of the ESLint plugin options simply update the eslintConfig key in your webpack.settings.js override file.

Alternatively, to just set the linting rules, you can drop an .eslintrc.js file as per normal usage in your site root folder.

Source Maps**

Out of the box, source maps are generated using webpack's "eval-source-map" devtool, which provides a "true" source map to the original code which makes debugging using breakpoints straightforward.

Other devtools for webpack are available which have different performance and accuracy characteristics. You can easily override the chosen devtool by adding a devtool option to your webpack.config.js overrides.

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

• Josh Smith - @batchnz - josh@batch.nz
• Jude Reid - @batchnz - jude@batch.nz

Project Link: https://github.com/batchnz/craft-webpack

Acknowledgements

• nystudio107 annotated webpack config
• nystudio107 twigpack