htmlprep

v2.0.2

Published

2 years ago

High-performance streaming HTML pre-processor designed to run in middleware.

Downloads

0High
0Medium
0Low

dvonlehman

4front html build preprocessor express

htmlprep

High-performance HTML pre-processor designed to be run in middleware, but also suitable for packaging up in a build task. Utilizes a streaming API based on htmlparser2. Useful when you need to apply basic markup modifications to HTML files at run-time and as a zero-config alternative to gulp and grunt plugins for optimizing release versions of HTML pages.

Makes use of standard-compliant data-* attributes to annotate the markup indicating where custom processing should occur. These attributes are stripped out of the final output, so the HTML sent down to the browser leaves no traces behind.

Intended as a light-weight HTML decorator rather than a full-blown template engine such as Jade. However it's certainly possible for HTML generated by Jade, or another template language, to be piped through htmlprep.

Example

Use in express route or middleware:

var htmlprep = require('htmlprep');

res.set('Content-Type', 'text/html');
fs.createReadStream('./views/index.html')
  .pipe(htmlprep({
    assetPathPrefix: '//cdnhost.com/dir'
  }))
  .pipe(res);

Features

Prepend prefix to asset URLs

Prepend a string to all src and link href attributes. Canonical use case is repointing assets to a CDN. If the assetPathPrefix option is set to "//cdnhost.com/assets" then:

<script src="/js/app.js"></script>
<img src="/images/logo.gif">

becomes:

<script src="//cdnhost.com/assets/js/app.js"></script>
<img src="//cdnhost.com/assets/images/logo.gif">

You can prevent this behavior for specific assets by providing a list of glob patterns to the noPathPrefixPatterns option. The value of the each asset path, i.e. /images/logo.gif is evaluated against each pattern using minimatch.

For example if you wanted all .jpg files in the images directory to be left alone, you'd do this:

htmlprep({
  assetPathPrefix: '//cdhhost.com/assets',
  noPathPrefixPatterns: ['/images/*.jpg']
});

Build-specific blocks

Omit HTML blocks or individual tags based on a custom build attribute. Useful for declaring which scripts or stylesheets should be present in release vs. debug mode.

<link rel="stylesheet" href="/css/layout.css" data-build="debug">
<link rel="stylesheet" href="/css/nav.css" data-build="debug">
<link rel="stylesheet" href="/dist/app.min.css" data-build="release">
<div data-build="debug">
    <script src="/js/app.js"></script>
    <script src="/js/models.js"></script>
    <script src="/js/controllers.js"></script>
</div>
<script src="dist/app.min.js" data-build="release">

When called with buildType:"debug" becomes:

<link rel="stylesheet" href="/css/layout.css">
<link rel="stylesheet" href="/css/nav.css">
<div>
    <script src="/js/app.js"></script>
    <script src="/js/models.js"></script>
    <script src="/js/controllers.js"></script>
</div>

And with buildType:"release":

<link rel="stylesheet" href="/dist/app.min.css">
<script src="dist/app.min.js">

Block injection

Inject blocks of HTML at render time to the <head> or <body> tags or to a named block specified with the data-placeholder attribute.

htmlprep({
 inject: {
  head: '<style>body {background-color:blue}</style>'
  body: '<!-- End of body -->',
  'before-nav': 'before nav',
  'after-nav': 'after nav'
 }
});

<html>
	<head>  
	</head>
 	<body>
	  	<div data-placeholder="before-nav"></div>
	  	<nav></nav>
		<div data-placeholder="after-nav"></div>
	</body>
</html>

becomes:

<html>
	<head>
   		<style>body { background-color:blue; }</style>
	</head>
	<body>
  		<div>before nav</div>
	  	<nav></nav>
	  	<div>after nav</div>
	  	<!-- End of body -->
	</body>
</html>

JavaScript and stylesheet expansion

Declare a single script or link with a glob pattern and automatically expand to individual elements for every matching file. File matches are relative to the directory specified in the cwd option.

<html>
	<head>
		<link rel="stylesheet" data-expand-href="css/**/*.css"/>
	</head>
	<body>
    	<script data-src-expand="js/**/*.js"></script>
	</body>
</html>

becomes:

<html>
	<head>
		<link rel="stylesheet" href="main.css"/>
		<link rel="stylesheet" href="layout.css"/>
	</head>
	<body>
    	<script src="js/app.js"></script>
    	<script src="js/blog.js"></script>
    	<script src="js/nav.js"></script>
  </body>
</html>

LiveReload

Appends the livereload script at the end of the body.

<script src="//localhost:35729/livereload.js"></script>

Options

All the possible attributes that can be specifed in the options parameter.

buildType - Remove all elements that have a data-build attribute whose value does not match the specified value.
liveReload - Specify if the localhost LiveReload script should be injected.
liveReloadPort - The port number for livereload.js, defaults to 35729.
assetPathPrefix - The string to prepend to all relative asset URLs. Works with script, link, img, and embed tags.
inject - Object of HTML blocks to inject over placeholders. The keys body and head will append to those respective tag names rather than a corresponding placeholder.
attrPrefix - Specify a custom prefix for data attributes. So instead of data-build, you could use data-myprefix-build.
cwd - The current working directory. Defaults to process.cwd.

Roadmap

User-Agent specific blocks

Exclude blocks of HTML where the request user-agent does not pass an expression test. Useful for including polyfill scripts conditionally or excluding content from mobile devices to lighten the HTML payload.

License

Licensed under the Apache License, Version 2.0.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

htmlprep

Example

Features

Prepend prefix to asset URLs

Build-specific blocks

Block injection

JavaScript and stylesheet expansion

LiveReload

Options

Roadmap

User-Agent specific blocks

License