README.md

Agency Webpack Mix Config

Featuring a top-class developer experience and simple filing system for your project assets, this config provides a solid platform for your next website (or web app).

Features

Sensible configuration complexity

Because of the complexity of raw Webpack configs, they can take an extended time to understand. Laravel Mix provides a simple layer upon Webpack to help make many build adjustments quick and painless.

Modern mainstream defaults

Use next generation JavaScript and CSS with polyfills automatically applied to the browsers you choose to support.

Development proxy with script and style injection

A pre-configured webpack development server rewards your code changes with snappy browser updates. Generate additional style and script outputs just by adding them to a folder in the src directory.

Static site generator

Get straight to the build with a static site generator that converts twig to html.
There's also full support for CMS based sites by updating a few config values.

Minimal config files

Avoid excessive build configuration files with all config defined in webpack.mix.js.
The package.json contains browser targets and linting configs.

Build actions

src/styles

Style files are compiled to CSS and PostCss plugins provide additional transformations and optimisations.

• Sass auto compiling, prefixing, minifying and sourcemaps
• CriticalCSS and PurgeCSS come preconfigured to improve your page speed
• Autoprefixer and PostCSS Preset Env provide support for older browsers

src/scripts

Script files are transpiled to vanilla JavaScript and the necessary polyfills included.

• Script transpiling with Babel with minifying and sourcemaps
• Automatic browser polyfills are provided by Core-Js 3
• ESLint is provided for error linting

src/images

Images are optimized and copied to the build directory.

• Optimisations are provided by Imagemin

src/icons

Individual SVG icons are optimised then combined into a single cacheable SVG.

• An async script adds the svg sprite to your page
• You can display an icon like this:
  

<svg><use xlink:href="icon-code" /></svg>

src/static

Additional folders with no transform requirements are copied to your build folders.

Getting started

1. Copy this repo into a new project folder:

npx degit ben-rogerson/agency-webpack-mix-config new-project

…or use Github's new tool to create a new repository then clone the project down.

2. Install the dependencies:

cd new-project && npm install

3. Update the proxy domain and start adding project files

This config allows for either static or dynamic template sites. Dynamic template sites could be ones running Craft, Wordpress, or Laravel.

a) Create a static site

This option converts the Twig templates in src/templates into static Html files and hashes assets during a production build.

1. Update the devProxyDomain in webpack.mix.js, eg:

   const config = {
     // ...
     devProxyDomain: "http://my-static-site.test",
   }

2. Then add your devProxyDomain to Valet/Homestead/Vagrant. If you're using Valet you can add it like this:

   cd web && valet link my-static-site.test

   You'll need to run npm run build to preview your static site operating at my-static-site.test.

3. npm run dev to start your development server.

b) Create a dynamic site

This option lets you use a CMS and during production it compresses and hashes assets and creates a manifest file.

You could add any CMS but in this example I'll copy in the files from the Craft CMS starter:

npx degit --force craftcms/craft

Craft CMS requires a templates directory in the base folder for their twig templates so I'll add these config values in webpack.mix.js:

const config = {
    // Dev domain to proxy
    devProxyDomain: "http://my-craft-site.test",
    // Paths to observe for changes
    devWatchPaths: ["templates"],
    // Folders where purgeCss can look for used selectors
    purgeCssGrabFolders: ["src", "templates"],
    // Build a static site from the src/template files
    buildStaticSite: false,
}

Then create a new project database, add the devProxyDomain to Valet/Homestead/Vagrant and finish the Craft install with composer install && ./craft setup.

Loading the files from the manifest

No matter what CMS you use, you'll need a way to reference the files from the mix-manifest.json file that's created. This example shows how to use Twigpack to load the files from the manifest.

Removing excess packages

There will be some unnecessary packages used only for rendering a static site. Remove them from your project:

npm rm html-webpack-plugin twig-html-loader laravel-mix-twig-to-html

Tasks

The following tasks are available:

npm run dev
# Run the development server

npm run start
# Run the development build

npm run build
# Run the production build

npm run fix-scripts
# Fix your javascript with eslint