tweltner/usemin

Replaces references to non-optimized scripts or stylesheets into a set of HTML files (or any templates/views)

usemin

API version of usemin. For purists, those who doesn't use build tools like Grunt and Gulp, but just use node as their build tool.

Getting started

Install with npm:

npm install usemin

CLI

usemin-cli - Command line interface for this module.

API

var usemin = require('usemin');

usemin(filepath, dest, [opts])

Replaces references to non-optimized scripts or stylesheets into a set of HTML files (or any templates/views).

Parameters:

(string) filepath - HTML input file path.

(string) dest - Directory for where the optimized scripts and stylesheets should go.

(object) opts Optional - See below for the available options.

Returns:

(string) The content of the final HTML file

options:

var defaults = {
	output: false, // HTML output path. If false, it will be printed to the console (string)
	configFile: false, // config file path for UglifyJS, CleanCSS and HTML minifier (string)
	config: false, // UglifyJS, CleanCSS and HTML minifier configs,
	               // similar format to the config file (object)
	hash: false, // append md5-hash value of bundle as suffix (bundle.js?v={MD5})
	htmlmin: false, // Whether to minify the input HTML file (Boolean)
	nobundle: false, // Whether to bundle block source files (Boolean)
	noprocess: false, // Do not process files, just replace references (Boolean)
	removeLivereload: false, // Remove livereload script (Boolean)
};

Examples

var html = usemin('src/index.html', 'dist');
usemin('src/index.html', 'dist', {
	output: 'dist/index.html',
	htmlmin: true,
	removeLivereload: true,
});

usemin.getBlocks(filepath, content, removeLivereload)

Extract information from a HTML input file to be processed later. This does not process any files (i.e., it doesn't perform uglify or minify).

Parameters:

(string) filepath - HTML input file path.

(string) content - Content of the HTML file as a string. (The reason for this is because the main usemin function uses this content multiple times, so to prevent the file being read multiples times it's simply cached into a variable to be passed into these API functions.)

(boolean) removeLivereload - Whether to also extract livereload script.

Returns:

(object) An object of the following form:

[
	{
		async: false,
		defer: false,
		type: 'css',
		dest: 'css/main.css',
		indent: '\t',
		searchPath: ['',],
		src: [
		   inputsDir + 'css/foo.css',
		   inputsDir + 'css/bar.css',
		],
		raw: [
		   '\t<!-- build:css css/main.css -->',
		   '\t<link rel="stylesheet" href="css/foo.css">',
		   '\t<link rel="stylesheet" href="css/bar.css">',
		   '\t<!-- endbuild -->',
		],
	},
]

usemin.getConfig(configFile, configOverride)

Returns configurations object for UglifyJS, CleanCSS and HTML minifier from a config file.

Parameters:

(string) configFile - Config file path. (.js extension can be omitted.) (object) configOverride - Config object to override any previously set configs.

returns:

(object) An object of the following form:

{
	uglifyjs: {
	},
	cleancss: {
	},
	htmlminifier: {
		removeComments: true,
		collapseWhitespace: true,
		removeEmptyAttributes: true,
		removeScriptTypeAttributes: true,
		removeStyleLinkTypeAttributes: true,
		minifyJS: true,
		minifyCSS: true,
	},
}

usemin.processBlocks(blocks, dest, config)

Uglify javascripts and CSS for a supplied block object from the usemin.getBlocks function.

Parameters:

(object[]) blocks - Blocks from the usemin.getBlocks function.

(string) dest - Directory for where the optimized scripts and stylesheets should go.

(object) config - Configuration object for UglifyJS, cleanCSS and HTML minifier.

Returns:

(boolean) Throws error, otherwise true.

usemin.getHtml(content, blocks, htmlmin, config, nobundle, hashing, dest)

Returns the HTML with replaced references to non-optimized scripts or stylesheets. nobundle parameter ensure, if block source files shall be bundled. hashing allows to hash created bundle file with md5 and append hash-value to the src= script tag. The dest parameter is necessary for hashing in order to find location of created bundle files.

Parameters:

(string) content - Content of the HTML file as a string. (The reason for this is because the main usemin function uses this content multiple times, so to prevent the file being read multiples times it's simply cached into a variable to be passed into these API functions.)

(object[]) blocks - Blocks from the usemin.getBlocks function.

(boolean) htmlmin - Whether to also minify the HTML.

(object) config - Configuration object for UglifyJS, cleanCSS and HTML minifier.

(boolean) nobundle - Whether to bundle javascript source files.

(boolean) hashing - Whether to create md5 hash of created bundle files and append to script tag.

(string) dest - Destination of usemin output. Is necessary in order to find created bundle files for hashing.

Returns:

(string) The content of the final HTML file

Example HTML

Blocks

Blocks are expressed as:

<!-- build:<pipelineId>(alternate search path) <path> -->
... HTML Markup, list of script / link tags.
<!-- endbuild -->

• pipelineId: pipeline id for options or remove to remove a section
• alternate search path: (optional) By default the input files are relative to the treated file. Alternate search path allows one to change that
• path: the file path of the optimized file, the target output

<!-- build:css css/main.js -->
<link rel="stylesheet" href="css/main.css">
<link rel="stylesheet" href="css/modules.css">
<!-- endbuild -->

<!-- build:js js/main.js -->
<script src="js/app.js"></script>
<script src="js/controllers.js"></script>
<!-- endbuild -->

<!-- build:js js/main.js -->
<script defer async src="js/app.js"></script>
<script defer async src="js/controllers.js"></script>
<!-- endbuild -->

<!-- build:remove -->
<script src="js/app.js"></script>
<script src="js/controllers.js"></script>
<!-- endbuild -->

<script>document.write('<script src="http://' + (location.host || 'localhost').split(':')[0] + ':35729/livereload.js?snipver=1"></' + 'script>')</script>

Running the command with --rmlr true will output:

<link rel="stylesheet" href="css/main.js">
<script src="js/main.js"></script>
<script defer async src="js/main.js"></script>

Alternate search path

<!-- build:js(js) js/main.js -->
<script defer async src="app.js"></script>
<script defer async src="controllers.js"></script>
<!-- endbuild -->

<!-- build:js(js,.tmp) js/main.js -->
<script defer async src="app.js"></script>
<script defer async src="controllers.js"></script>
<!-- endbuild -->

Config file

Please check the relevant documentations for the available options: UglifyJS, CleanCSS and HTML minifier.

module.exports = {
	uglifyjs: {
		// ... UglifyJS API options
	},
	cleancss: {
		// ... CleanCSS API options
	},
	htmlminifier: {
		// ... HTML minifier API options
	}
}

In order to create single *.map file for each block defined in html document, the outSourceMap options of uglifyjs is extended. It is now possible to pass only the boolean value true in order to generate the corresponding *.map file for the block.

<!-- build:js(js) js/main.js -->
<script defer async src="app.js"></script>
<script defer async src="controllers.js"></script>
<!-- endbuild -->

<!-- build:js(js) js/external.js -->
<script defer async src="app.js"></script>
<script defer async src="controllers.js"></script>
<!-- endbuild -->

When setting uglifyjs config outSourceMap to true, then a main.js.map and external.js.map file will be generated.

It is also possible to set a prefix numeric value in ordert to revise sources path generated in sourcemap files. More details on the prefix option is available in official UglifyJS2 documentation

module.exports = {
	uglifyjs: {
		outSourceMap: true,
		prefix: 2,
	}
}

License

MIT license