README

(with Webpack 5, Tailwind 2, PostCSS 8, and HMR, and other goodies)

A real-world boilerplate for Craft CMS 3 projects that leverages Wepback 5, Tailwind 2, PostCSS 8, and Twigpack. Also included is a hot-reload dev environment. I created this as a starting point for Craft CMS 3 / Webpack 5 projects.

This project was originally created by https://github.com/mizziness/craft3-webpack5-tailwind2-boilerplate

What's Included

• Craft CMS 3 - My CMS of choice, and the app which will consume assets from Webpack.
• Webpack 5 - Bundling, optimizing, and serving your assets
• Twigpack - The bridge between Craft CMS and Webpack
• TailwindCSS 2 - Awesome CSS framework that makes dev speedy
• SASS - SASS/SCSS Support
• PostCSS - Post-processing CSS Files

Other included tools/plugins

Webpack

• webpack - Module and asset bundler.
• webpack-cli - Command line interface for webpack
• webpack-dev-server - Development server for webpack
• webpack-merge - Simplify development/production configuration
• cross-env - Cross platform configuration

Transpiling

• @babel/core - Transpile ES6+ to backwards compatible JavaScript
• @babel/plugin-proposal-class-properties - Use properties directly on a class (an example Babel config)
• @babel/preset-env - Smart defaults for Babel
• babel-loader - Transpile files with Babel and webpack

Loaders, Sass, Plugins

• sass-loader - Load SCSS and compile to CSS
• sass - Dart Sass
• fibers - Increase Dart Sass performance (see note here
• postcss-loader - Process CSS with PostCSS
• postcss-preset-env - Sensible defaults for PostCSS
• css-loader - Resolve CSS imports
• style-loader - Inject CSS into the DOM
• clean-webpack-plugin - Remove/clean build folders
• webpack-manifest-plugin - Create Manifest.json file with chunks
• html-webpack-plugin - Generate HTML files from template
• mini-css-extract-plugin - Extract CSS into separate files
• css-minimizer-webpack-plugin - Optimize and minimize CSS assets

Get Started

First, finish up installing Craft CMS locally for your development environment:

$ composer install
$ ./craft setup

Then install our other packages and run the HMR development server:

$ yarn install
$ yarn dev

(I use yarn for my project, but you don't need to - use the tool of your choice.)

Webpack assets are set up to serve from localhost:8080 by default.

You can include your chunked/hashed assets in Craft CMS templates by using Twigpack's features:

{{ craft.twigpack.includeCssModule("app.css", true) }}
{{ craft.twigpack.includeJsModule("app.js", true, {"type": "module"}) }}
{{ craft.twigpack.includeJsModule("chunk-vendors.js", true) }}

Scripts

As you can see in the package.json file, there are 3 included scripts for convenience:

• yarn dev - Runs the HMR development server
• yarn build - Creates a production-ready build for deployment (asset output is in web/dist)
• yarn clean - A quick way to clear Craft CMS caches while you code

Make it Yours

This project comes pre-configured out of the box to work with Craft CMS templates, but there are plenty of ways you can customize the way this works to suit your own needs. It tries to make no assumptions about your toolkit, other than the minimum required configuration to work with the tools included.

• Tailwind has been set up with with a default configuration, and I highly suggest modifying it for your project. (You can overwrite it with an existing tailwind.config.js file, if you have one, to import all your custom styling quickly.)
• devServer options can be changed and extended as needed - for example, by default auto open for the served url is turned off, but if you're using a custom generated template, then you might want it on, instead.
• Go to town!

Prettier Webpack

If you're like me and you prefer a cleaner webpack report, try this:

yarn add webpackbar -D

In the wpconfig files, you'll see two commented-out lines which you can uncomment to enable a much nicer view of your webpack report with webpackbar.

Inspired By

And used as a starting point: https://github.com/taniarascia/webpack-boilerplate

License

This project is open source and available under the MIT License.