Web-Combiner: Assets Combiner

README.md

Web-Combiner

A CSS, JS, and Handlebars combiner, compressor, and server

The idea

A middleware that knows how to combine, compress and serve CSS and JS files.

When the route is triggered, Web Combiner grab one of the params css and js to create the final result with those files if them exists, otherwise it throws an Error with status 404.

Cache Strategy

We create files on the application cache storage by using a base64 based on the files required and params like this example

# cache pattern
[cache]/[version]/[base_64_name].[ext]

# CSS request with a specify version
/combiner/c?v=8&css=module/file.css,fonts/customfont.css,pages/main.css&disableOptimizations=false&minify=false

# Generated Hash/File
bW9kdWxlL2ZpbGUuY3NzLGZvbnRzL2N1c3RvbWZvbnQuY3NzLHBhZ2VzL21haW4uY3NzJmRpc2FibGVPcHRpbWl6YXRpb25zPWZhbHNlJm1pbmlmeT1mYWxzZQ==

# JavaScript request (simple)
/combiner/c?js=globals/index.js,vendor/jquery.min.js,pages/main.js

# Generated Hash/File
Z2xvYmFscy9pbmRleC5qcyx2ZW5kb3IvanF1ZXJ5Lm1pbi5qcyxwYWdlcy9tYWluLmpz

# File system
.
├── /app
│
├── /public
│   └── /assets
└── /[cache]
    ├── Z2xvYmFscy9pbmRleC5qcyx2ZW5kb3IvanF...
    └── v8
        └── bW9kdWxlL2ZpbGUuY3NzLGZvbnRzL2N...

How to use

The Load Path

const combiner = require('web-combiner');

const assets = {
  cache: false,
  errorHandler: null,
  uglifyJsModule: null,
  cssPatch: './public/assets/stylesheets',
  jsPatch: './public/assets/javascripts',
};

combiner(assets);

• cache : String | false The directory for cache storage (must be writeable). Pass false to cache in the memory (not recommended). If you want to disable cache for specific response, see LINK.

• uglifyJsModule : Object Customize UglifyJS (>= 3) module. If not specified, it will be require('uglify-js').

• errorHandler : Function(errorInfo, callback) Function to handle compiling and minifying errors. You can determine what to respond for specific kind of error. See LINK.

• cssPatch : String | RegExp | false The logical path where your CSS files are located.

• jsPatch : String | RegExp | false The logical path where your CSS files are located.

Serving Assets Over HTTP

const express = require('express');
const combiner = require('web-combiner');
const config = require('../config/combiner/assets.json');

const app = express();

// Destination where the cached assets will be generated
app.use(combiner(config))

Loading assets:

# Usage 
/combiner/c?v=1&css=module/file.css,fonts/customfont.css,pages/main.css&disableOptimizations=true&minify=false
/combiner/c?v=8&js=globals/index.js,vendor/jquery.min.js,pages/main.js

Parameters:

The url support the follow parameters:

Param	Value	Example	Description
v	string	v=10	Returns a specific version from cache
css	string	css=path/file.css,fonts/custom.css	Returns css files combined by using file paths
js	string	js=path/main.js,vendor/plugin.min.js	Returns javascript files combined by using file paths
minify	boolean	minify=false	Enable/Disable the minification of the assets (Default=true)
disableOptimizations	boolean	disableOptimizations=false	Enable/Disable small optimization for the assets by using uglify.js, cssnano, and few others. (Default=true)