A simple and lightweight build process with Sass, svg-sprite-generator and browser-sync.
Greatly inspired by the article Why npm scripts? and the repo associated npm-build-boilerplate (including the list of available tasks in this README)
This repo also contains some js utility functions, a scss boilerplate and some example files in the src and the production folders for a better understanding, feel free to delete or replace them.
To use this project you have to have node.js & npm both installed and be familiar with how npm scripts works.
If this build process is only used for one project, use the command line npm install in your directory, otherwise consider installing globally the scripts listed in dev dependencies inside the package.json (you don't need a heavy node_modules folder in every single project!).
In order to use the PurgeCSS command, you must have installed it globally using npm i -g purgecss. If you want to install it locally, you can run npm i -D purgecss and launch the purgeCSS command using npx.
The tasks are written to work with this file structure :
|-- dist # Production files
|-- css # css
|-- icons # svg sprite
|-- svg # Cleaned individual svgs
|-- js # js
|-- src # Source files
|-- icons
|-- js
|-- scss
|-- browser-sync.config.js # Config for Browser-sync
|-- rollup.config.mjs # Config for Rollup
|-- svg.config.json # Config for svg-sprite
|-- index.html # Your index file
If you change it, don't forget to modify the associated scripts in package.json and inside the config files.
sass --error-css --style=compressed --no-source-map --update src/scss:dist/css
Compile Scss to CSS (using Dart Sass)
postcss --no-map -u autoprefixer postcss-combine-media-query postcss-combine-duplicated-selectors --r dist/css/*
Add vendor prefixes to your CSS automatically & combine selectors/media queries
purgecss --css dist/css/styles.css --content **/*.html **/*.js **/*.php --output dist/css/styles.purged.css
Remove unused CSS rules, the content option specify the files to crawl in order to determine which rules are used. (Here, any html, js or php file in any subfolder).
Output the result to the styles.purged.css file.
rollup --config
Bundle javascript files using js modules in a single js file (app.js) with Tree Shaking (doesn't bundle unused functions, perfect if you want to store utilities). It also allows us to stay compatible with more browsers.
This build process no longer transpile ES2015 code to be ES5 compatible because the support is good enough for most of the projects I work on, but if you need to support older browsers (like IE11), you might want to checkout this plugin : @rollup/plugin-buble
terser dist/js/app.js -m -o dist/js/app.min.js
Uglify (minify) a production ready bundle of JavaScript using Terser (Which seems to be the best option for ES2015 minification).
svgo -f src/icons -o dist/icons/svg && svg-sprite --config svg.config.json dist/icons/svg/*.svg
Compress separate SVG files to the dist/icons/svg directory and combine them into one SVG "sprite" using the config inside the config.json file
The use of this sprite and how to create an SVG icon system is wonderfully explained in this page : SVG Icon System
run-s scss autoprefixer purgecss
Alias to run the scss, purgecss and autoprefixer tasks. Compiles Scss to CSS, add vendor prefixes and remove unused rules.
You might want to checkout that everything is working as expected when you switch to the purged css file, some very specific css rules might get lost in the process. You can add exceptions with the --safelist flag
run-s bundle uglify
Alias to run the bundle and uglify tasks.
npm run icons
Alias to run the icons task.
onchange \"src/**/*.scss\" -- run-s scss
Watches for any .scss file in src to change, then runs the scss task.
It does not run the autoprefixer and purgecss command, which would be too long to execute at every file change.
onchange \"src/**/*.js\" -- run-s bundle uglify
Watches for any .js file in src to change, then runs the bundle and uglify task
onchange \"src/icons/*.svg\" -- run-s icons
Watches for any .svg file in src to change, then runs the icons task
browser-sync start --config browser-sync.config.js
Start a new server and watch for CSS, JS, HTML or PHP file changes.
if your project is already running on a server, you have to modify the browser-sync.config.js file by commenting the "server" line and uncommenting + modifying the "proxy" line if needed.
run-p serve watch:*
Run the following tasks simultaneously: serve, watch:css, watch:js and watch:icons. When a .scss, .js or .svg file changes in src, the task will compile the changes to the respective folders, and the server will be notified of the change. Any browser connected to the server will then inject the new file.
A css change does not trigger a full-page reload, the changes are discrete.
run-p build:*
Build the production files without launching a server.
This build process is developed and maintained by Rachel Pellin for personal projects and Webtopie clients.
Contributions are not open, this project is personal, but feel free to fork it to adapt to your own needs!
webtopie-build-process is licensed under the MIT License