newcity/stonemason repository overview

⁠Stonemason: NewCity's multipurpose compiler

⁠Tailwind Version Notice

TailwindCSS launched version 2.0 in November 2020. While it is largely compatible, it is not a drop-in replacement for version 1.x. If you are working on a project that was built using a version 1 variant of Tailwind, make sure to tag your docker image with the version number (e.g. newcity/stonemason:tailwind-1).

For details about the changes between versions, visit https://tailwindcss.com/docs/upgrading-to-v2⁠

⁠What it does

Stonemason takes source files from a mounted volume and processes them according to stages set in a configuration file that is also mounted. Out of the box, it is set up to support compiling SCSS with optional TailwindCSS, transpiling JavaScript with Babel, and converting SVG icons into SVG spritesheets. It can also copy files directly from a source directory to a destination directory.

⁠How it does it

The 1.0 version of Stonemason uses Laravel Mix⁠ as a wrapper around WebPack⁠. The Docker image has a pre-installed set of plugins for mix, webpack, and TailWindCSS⁠. You can use all of them or none of them depending on your project's needs. You can also mount your own package.json file to install additional NPM dependencies that you can then use in your config.

⁠Preinstalled Tools

• TailWindCSS⁠
• Babel polyfill
• @ayctor/laravel-mix-svg-sprite
• laravel-mix-string-replace
• SCSS / PostCSS (no plugins except for TailWind by default)

⁠How to use it

1. Create a directory to house your source files, e.g. src. When configuring your docker-compose.yml file, mount that directory as /app/src in the volumes section.

2. Create webpack.mix.js file. Set it up according to the normal laravel mix process, with the following exceptions:

   • Instead of requiring laravel-mix directly, put these two lines near the top of your config file:

     const assetPaths = require('./webpack-default.mix.js').buildPaths();
     const mix = require('./webpack-default.mix.js').defaultMix(assetPaths);
     

     Copy

   • You do not need to do anything special to copy images or fonts directly into the output directory. Simply create directories at src/images and/or src/fonts and put your static image and font files there.

   • You can use the .polyfill(), .svgSprite(), or .stringReplace() without requiring them in your own config file. They are already part of the default webpack mix object.

   • If you are using .svgSprite(), you should add the following to your config, below where you defined assetPaths:

     const spritePrefixer = require('./webpack-default.mix.js').spritePrefixer(assetPaths);
     

     Copy

     You can then use the spritePrefixer function within your options object for the svgSprite() step:

     output: {
        filename: `dist/icons/icon-sprites.svg`,
        svg4everybody: true,
     },
     sprite: {
        prefix: spritePrefixer,
     }
     

     Copy