Skip to content

A simple and lightweight build process of npm scripts with Sass, Rollup, svg-sprite and browser-sync

License

Notifications You must be signed in to change notification settings

rachelwe/webtopie-build-process

Repository files navigation

webtopie-build-process

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.

Usage

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.

If you want to use the documentation script, you also need to install it globally for it to work using the command npm i -g retypeapp

Folder structure

The task 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
|-- rollup.config.json    # Config for Rollup
|-- svg.config.json       # Config for svg-sprite
|-- retype.yml            # Config for Retype docs
|-- 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.

List of available tasks

scss

sass --error-css --style=compressed --no-source-map --update src/scss:dist/css

Compile Scss to CSS (using Dart Sass)

autoprefixer

postcss --no-map -u autoprefixer --r dist/css/*

Add vendor prefixes to your CSS automatically

purgecss

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.

bundle

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

uglify

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).

icons

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

build:css

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

build:js

run-s bundle uglify

Alias to run the bundle and uglify tasks.

build:icons

npm run icons

Alias to run the icons task.

watch:css

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.

watch:js

onchange \"src/**/*.js\" -- run-s bundle uglify

Watches for any .js file in src to change, then runs the bundle and uglify task

watch:icons

onchange \"src/icons/*.svg\" -- run-s icons

Watches for any .svg file in src to change, then runs the icons task

serve

browser-sync start --server --files \"**/*.css, **/*.min.js, **/*.html, **/*.php\""

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 this line to look like this (just replace YOUR-LOCAL-SERVER-URL) :

browser-sync start --proxy http://YOUR-LOCAL-SERVER-URL --files \"css/*.css, js/*.js, *.html, *.php\"

dev

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.

build

run-p build:*

Build the production files without launching a server.

docs:js

jsdoc2md src/js/**/*.js > js.md

Generates a markdown file from the js docs comments

docs:generator

retype build

Generates a documentation folder from all the markdown files in the project.

docs

run-s docs:js docs:generator

Generates all the docs.

Author

This build process is developed and maintained by Rachel Pellin for personal projects and Webtopie clients.

Twitter LinkedIn

Contributions

Contributions are open, feel free to post an issue if you have any problem.

License

webtopie-build-process is licensed under the MIT License

About

A simple and lightweight build process of npm scripts with Sass, Rollup, svg-sprite and browser-sync

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published