# @ladjs/consolidate [![build status](https://github.com/ladjs/consolidate/actions/workflows/ci.yml/badge.svg)](https://github.com/ladjs/consolidate/actions/workflows/ci.yml) [![code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo) [![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier) [![made with lass](https://img.shields.io/badge/made_with-lass-95CC28.svg)](https://lass.js.org) [![license](https://img.shields.io/github/license/ladjs/consolidate.svg)](LICENSE) > Modern and maintained fork of the template engine consolidation library. Maintained and supported by Forward Email , the 100% open-source and privacy-focused email service. > **NOTE:** This package `@ladjs/consolidate` also mirrors to `consolidate` on npm, however you should upgrade to `@ladjs/consolidate` as we may deprecate `consolidate` in the future. ## Install ```sh npm install @ladjs/consolidate ``` ## Engines Some package has the same key name, `@ladjs/consolidate` will load them according to the order number. By example for dust, `@ladjs/consolidate` will try to use in this order: `dust`, `dustjs-helpers` and `dustjs-linkedin`. If `dust` is installed, `dustjs-linkedin` will not be used by `@ladjs/consolidate`. | Name `cons.*` | Package Name / Order | Website / State | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | [atpl](https://github.com/soywiz/atpl.js) | [`npm install atpl`](https://www.npmjs.com/package/atpl) | - | | [bracket](https://github.com/danlevan/bracket-template) | [`npm install bracket-template`](https://www.npmjs.com/package/bracket-template) | - | | [dot](https://github.com/olado/doT) | [`npm install dot`](https://www.npmjs.com/package/dot) | [(website)](http://olado.github.io/doT/) | | ~~[dust](https://github.com/akdubya/dustjs)~~ | [`npm install dust`](https://www.npmjs.com/package/dust) (1) | [(website)](http://akdubya.github.com/dustjs/) / **(unmaintained)**
See: dustjs-linkedin | | [dust](https://github.com/linkedin/dustjs) | [`npm install dustjs-helpers`](https://www.npmjs.com/package/dustjs-helpers) (2) or
[`npm install dustjs-linkedin`](https://www.npmjs.com/package/dustjs-linkedin) (3) | [(website)](http://linkedin.github.io/dustjs/) | | ~~[eco](https://github.com/sstephenson/eco)~~ | [`npm install eco`](https://www.npmjs.com/package/eco) | **/!\ [Security issue](https://github.com/sstephenson/eco/pull/67)** | | [ect](https://github.com/baryshev/ect) | [`npm install ect`](https://www.npmjs.com/package/ect) | [(website)](http://ectjs.com/) | | [ejs](https://github.com/mde/ejs) | [`npm install ejs`](https://www.npmjs.com/package/ejs) | [(website)](http://ejs.co/) | | [eta](https://github.com/eta-dev/eta) | [`npm install eta`](https://www.npmjs.com/package/eta) | [(website)](https://eta.js.org/) | | [hamlet](https://github.com/gregwebs/hamlet.js) | [`npm install hamlet`](https://www.npmjs.com/package/hamlet) | - | | [hamljs](https://github.com/visionmedia/haml.js) | [`npm install hamljs`](https://www.npmjs.com/package/hamljs) | - | | [haml-coffee](https://github.com/netzpirat/haml-coffee) | [`npm install haml-coffee`](https://www.npmjs.com/package/haml-coffee) | - | | [handlebars](https://github.com/wycats/handlebars.js/) | [`npm install handlebars`](https://www.npmjs.com/package/handlebars) | [(website)](http://handlebarsjs.com/) | | [hogan](https://github.com/twitter/hogan.js) | [`npm install hogan.js`](https://www.npmjs.com/package/hogan.js) | [(website)](http://twitter.github.com/hogan.js/) | | [htmling](https://github.com/codemix/htmling) | [`npm install htmling`](https://www.npmjs.com/package/htmling) | - | | ~~[jade](https://github.com/visionmedia/jade)~~ | [`npm install jade`](https://www.npmjs.com/package/jade) | [(website)](http://jade-lang.com/) / **(renamed `pug`)** | | [jazz](https://github.com/shinetech/jazz) | [`npm install jazz`](https://www.npmjs.com/package/jazz) | - | | ~~[jqtpl](https://github.com/kof/jqtpl)~~ | [`npm install jqtpl`](https://www.npmjs.com/package/jqtpl) | **(deprecated)** | | [just](https://github.com/baryshev/just) | [`npm install just`](https://www.npmjs.com/package/just) | - | | [liquid](https://github.com/leizongmin/tinyliquid) | [`npm install tinyliquid`](https://www.npmjs.com/package/tinyliquid) | [(website)](http://liquidmarkup.org/)
**will never add any new features** | | [liquor](https://github.com/chjj/liquor) | [`npm install liquor`](https://www.npmjs.com/package/liquor) | - | | [lodash](https://github.com/bestiejs/lodash) | [`npm install lodash`](https://www.npmjs.com/package/lodash) | [(website)](http://lodash.com/) | | ~~[marko](https://github.com/marko-js/marko)~~ | [`npm install marko`](https://www.npmjs.com/package/marko) | [(website)](http://markojs.com) | | [mote](https://github.com/satchmorun/mote) | [`npm install mote`](https://www.npmjs.com/package/mote) | [(website)](http://satchmorun.github.io/mote/) | | [mustache](https://github.com/janl/mustache.js) | [`npm install mustache`](https://www.npmjs.com/package/mustache) | - | | [nunjucks](https://github.com/mozilla/nunjucks) | [`npm install nunjucks`](https://www.npmjs.com/package/nunjucks) | [(website)](https://mozilla.github.io/nunjucks) | | [plates](https://github.com/flatiron/plates) | [`npm install plates`](https://www.npmjs.com/package/plates) | - | | [pug](https://github.com/pugjs/pug) | [`npm install pug`](https://www.npmjs.com/package/pug) | [(website)](http://jade-lang.com/) / **(formerly jade)** | | [qejs](https://github.com/jepso/QEJS) | [`npm install qejs`](https://www.npmjs.com/package/qejs) | - | | [ractive](https://github.com/ractivejs/ractive) | [`npm install ractive`](https://www.npmjs.com/package/ractive) | - | | ~~[razor](https://github.com/kinogam/kino.razor)~~ | [`npm install razor`](https://www.npmjs.com/package/razor) | - | | [react](https://github.com/facebook/react) | [`npm install react`](https://www.npmjs.com/package/react) | - | | [slm](https://github.com/slm-lang/slm) | [`npm install slm`](https://www.npmjs.com/package/slm) | - | | ~~[squirrelly](https://github.com/squirrellyjs/squirrelly)~~ | [`npm install squirrelly`](https://www.npmjs.com/package/squirrelly) | [(website)](https://squirrelly.js.org) | | ~~[swig](https://github.com/paularmstrong/swig)~~ | [`npm install swig`](https://www.npmjs.com/package/swig) (1) | **(unmaintained)**
See: swig-templates | | [swig](https://github.com/node-swig/swig-templates) | [`npm install swig-templates`](https://www.npmjs.com/package/swig-templates) (2) | - | | [teacup](https://github.com/goodeggs/teacup) | [`npm install teacup`](https://www.npmjs.com/package/teacup) | - | | [templayed](https://github.com/archan937/templayed.js/) | [`npm install templayed`](https://www.npmjs.com/package/templayed) | [(website)](http://archan937.github.com/templayed.js/) | | [toffee](https://github.com/malgorithms/toffee) | [`npm install toffee`](https://www.npmjs.com/package/toffee) | - | | [twig](https://github.com/justjohn/twig.js) | [`npm install twig`](https://www.npmjs.com/package/twig) | [(wiki)](https://github.com/twigjs/twig.js/wiki/Implementation-Notes) | | [twing](https://github.com/NightlyCommit/twing) | [`npm install twing`](https://www.npmjs.com/package/twing) | [(website)](https://nightlycommit.github.io/twing/) | | [underscore](https://github.com/documentcloud/underscore) | [`npm install underscore`](https://www.npmjs.com/package/underscore) | [(website)](http://underscorejs.org/#template) | | [vash](https://github.com/kirbysayshi/vash) | [`npm install vash`](https://www.npmjs.com/package/vash) | - | | [velocityjs](https://github.com/julianshapiro/velocity) | [BETA](https://www.npmjs.com/package/velocity-animate) | [(website)](http://velocityjs.org/) | | [walrus](https://github.com/jeremyruppel/walrus) | [`npm install walrus`](https://www.npmjs.com/package/walrus) | [(website)](http://documentup.com/jeremyruppel/walrus/) | | [whiskers](https://github.com/gsf/whiskers.js) | [`npm install whiskers`](https://www.npmjs.com/package/whiskers) | - | **NOTE**: you must still install the engines you wish to use, add them to your package.json dependencies. ## API All templates supported by this library may be rendered using the signature `(path[, locals], callback)` as shown below, which happens to be the signature that Express supports so any of these engines may be used within Express. **NOTE**: All this example code uses cons.swig for the swig template engine. Replace swig with whatever templating you are using. For example, use cons.hogan for hogan.js, cons.pug for pug, etc. `console.log(cons)` for the full list of identifiers. ```js const cons = require('@ladjs/consolidate'); cons.swig('views/page.html', { user: 'tobi' }, function(err, html) { if (err) throw err; console.log(html); }); ``` Or without options / local variables: ```js const cons = require('@ladjs/consolidate'); cons.swig('views/page.html', function(err, html) { if (err) throw err; console.log(html); }); ``` To dynamically pass the engine, simply use the subscript operator and a variable: ```js const cons = require('@ladjs/consolidate'); const name = 'swig'; cons[name]('views/page.html', { user: 'tobi' }, function(err, html) { if (err) throw err; console.log(html); }); ``` ### Promises Additionally, all templates optionally return a promise if no callback function is provided. The promise represents the eventual result of the template function which will either resolve to a string, compiled from the template, or be rejected. Promises expose a `then` method which registers callbacks to receive the promise's eventual value and a `catch` method which the reason why the promise could not be fulfilled. Promises allow more synchronous-like code structure and solve issues like race conditions. ```js const cons = require('@ladjs/consolidate'); cons.swig('views/page.html', { user: 'tobi' }) .then(console.log) .catch(console.error); ``` ### Async/await ```js const cons = require('@ladjs/consolidate'); const html = await cons.swig('views/page.html', { user: 'tobi' }); console.log(html); ``` ## Caching To enable caching simply pass `{ cache: true }`. Engines *may* use this option to cache things reading the file contents, compiled `Function`s etc. Engines which do *not* support this may simply ignore it. All engines that `consolidate` implements I/O for will cache the file contents, ideal for production environments. When using consolidate directly: `cons.swig('views/page.html', { user: 'tobi', cache: true }, callback);` Using supported Express versions: `app.locals.cache = true` or set NODE\_ENV to `"production"` and Express will do this for you. ## Express example ```js const express = require('express'); const cons = require('@ladjs/consolidate'); const app = express(); // assign the swig engine to .html files app.engine('html', cons.swig); // set .html as the default extension app.set('view engine', 'html'); app.set('views', __dirname + '/views'); const users = []; users.push({ name: 'tobi' }); users.push({ name: 'loki' }); users.push({ name: 'jane' }); app.get('/', function(req, res) { res.render('index', { title: '@ladjs/consolidate' }); }); app.get('/users', function(req, res) { res.render('users', { title: 'Users', users: users }); }); app.listen(3000); console.log('Express server listening on port 3000'); ``` ## Template Engine Instances Template engines are exposed via the `cons.requires` object, but they are not instantiated until you've called the `cons[engine].render()` method. You can instantiate them manually beforehand if you want to add filters, globals, mixins, or other engine features. ```js const cons = require('@ladjs/consolidate'); const nunjucks = require('nunjucks'); // add nunjucks to requires so filters can be // added and the same instance will be used inside the render method cons.requires.nunjucks = nunjucks.configure(); cons.requires.nunjucks.addFilter('foo', function() { return 'bar'; }); ``` ## Notes * If you're using Nunjucks, please take a look at the `exports.nunjucks.render` function in `lib/consolidate.js`. You can pass your own engine/environment via `options.nunjucksEnv`, or if you want to support Express you can pass `options.settings.views`, or if you have another use case, pass `options.nunjucks` (see the code for more insight). * You can pass **partials** with `options.partials` * For using **template inheritance** with nunjucks, you can pass a loader with `options.loader`. * To use **filters** with tinyliquid, use `options.filters` and specify an array of properties, each of which is a named filter function. A filter function takes a string as a parameter and returns a modified version of it. * To use **custom tags** with tinyliquid, use `options.customTags` to specify an array of tag functions that follow the tinyliquid [custom tag](https://github.com/leizongmin/tinyliquid/wiki/Custom-Tag) definition. * The default directory used with the **include** tag with tinyliquid is the current working directory. To override this, use `options.includeDir`. * `React` To render content into an HTML base template (eg. `index.html` of your React app), pass the path of the template with `options.base`. ## Contributors | Name | Website | | ------------------ | -------------------------- | | **Forward Email** | | | **TJ Holowaychuk** | | ## License [MIT](LICENSE) © TJ Holowaychuk