measy

Create files using any template engine as simple as possible. Just a template and a JSON/YAML file is enough.

• Usage
• Install
• Examples
  • CLI Example
  • Template Example
• Details
  • Front Matter
  • CLI Options
  • Custom Helpers & Filters
  • Supported Template Engines

Usage

$ npx measy README.hbs

Install

$ npm install measy
$ yarn add measy

NOTE: If you wish to use template engines other than nunjucks or handlebars, you must install the engines you wish to use: Add them to your package.json dependencies or install globally.

Examples

CLI Example

• Create README.md from nunjucks template using package.json data:

$ measy README.njk

• without Front Matter, load data from package.json and foo.yaml

$ measy --context-files package.json,foo.yaml --out README.md README.njk

• Create a text file from handlebars template:

$ measy --context '{ codeName: "Jay" }' --out last.txt member.hbs

• Process all templates in a given directory:

$ measy --out docs my-templates

• Get help

$ measy --help

Template Example

Templates support Front Matter data in YAML format.

README.njk, README.hbs etc.

---
contextFiles: "package.json"
targetExtension: "md"
---
# {{ package.name }}

{{ package.description }}

# Examples

...some examples

Details

measy is simple command which creates files from templates combining data from JSON or JavaScript (or TypeScript with the help of ts-node) files. JSON files are parsed using JSON5. JS files can be used by exporting an object with module.exports or export default.

Front Matter

Any template file may contain a YAML front matter block. Data is processed by measy. The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed (---) lines. Here is a basic example:

---
contextFiles: "package.json"
rootContextFiles: ["some.json", "lib/my-data.js"]
partialDirs: ["templates/partials"]
functionFiles: "helper.js"
rootFunctionFiles: "other-helper.js"
targetExtension: "md"
---

| Name | Type | Description | | ----------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | contextFiles | string|string[] | js, ts, JSON5 or YAML file names or array of file names get context data for template. File name without extension is used as key in context data. | | rootContextFiles | string|string[] | js, ts, JSON5 or YAML file name or array of file names to get context data for template. Result is merged into context directly. | | targetExtension | string | If there is no out attribute, sets filename extension of output file. | | functionFiles | string|string[] |  Files to get filter/helper functions prefixed with file name. i.e "uc()" func in "path/helper.js" becomes "helperUc" helper/filter. | | rootFunctionFiles | string|string[] | Files to get filter/helper functions prefixed with file name. i.e "uc()" func in "path/helper.js" becomes "uc" helper/filter.  | | partialDirs | string|string[] | Path or array of paths relative to file to get partials from. |

Example

package.json

{
  "name": "some-module",
  "version": "1.0.0"
}

// contextFiles: "package.json"
{
  someOtherData: "Hello",
  package: {
    name: "some-module",
    version: "1.0.0"
  }
}

// rootContextFiles: "package.json"
{
  someOtherData: "Hello",
  name: "some-module",
  version: "1.0.0"
}

CLI Options

| Option Name | Description | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | --template-extension (Required) | File extension of the templates. | | --target-extension <extension> | File extension to be used in generated files. If template file has 'extension' meta data (frontmatter), extension in meta data has higher precedence. | | --out <path> | File path (for templates) or directory path (for directory input) to generate files into. Defaults to <template path>. | | --context <json5> | Data to be passed to templates. | | --context-files <paths> | js, ts, JSON5 or YAML files to get data to be passed to templates under a key same as file name. | | --root-context-files | js, ts, JSON5 or YAML files to get data to be passed to templates. | | --partial-dirs <paths csv> | Paths of directories which contains partial files. | | --function-files <paths csv> | Files to get filter/helper functions prefixed with file name. i.e "uc()" func in "path/helper.js" becomes "helperUc" helper/filter. | | --root-function-files <paths csv> | Files to get filter/helper functions prefixed with file name. i.e "uc()" func in "path/helper.js" becomes "uc" helper/filter. | | --exclude-paths <paths csv> | Paths to be excluded (for directory input only) | | --engine <engine name> | Template engine to be used. Supports engines supported by consolidate. | | --include-meta | Whether to include meta data in generated files. | | --debug | Print stack trace in errors. | | --silence | Prevent console output. |

Custom Helpers & Filters

measy allows you to use your own custom handlebars helpers and nunjucks filters.

Either export functions directly or export an object with names and functions from a JavaScript file.

You may add helpers/filters either using --root-function-files & --function-files CLI options or rootFunctionFiles & functionFiles front matter header in templates.

my-helper.js

export default {
  ucFirst: (input) => input.charAt(0).toUpperCase() + input.slice(1),
}

my-helper.js

export function ucFirst(input) {
  return input.charAt(0).toUpperCase() + input.slice(1);
}

Using Helpers/Filters with Front Matter

$ measy README.njk

README.njk

---
rootFunctionFiles: "my-helper.js"
---
Hello {{  firstName | ucFirst  }}

README.hbs

---
rootFunctionFiles: "my-helper.js"
---
Hello {{  ucFirst firstName  }}

Using Helpers/Filters with Front Matter

$ measy --root-function-files my-helper.js README.njk

README.njk

Hello {{  firstName | ucFirst  }}

README.hbs

Hello {{  ucFirst firstName  }}

Supported Template Engines

Thanks to Consolidate.js

• atpl
• bracket
• doT.js (website)
• dust (unmaintained) (website)
• dustjs-linkedin (maintained fork of dust) (website)
• eco
• ect (website)
• ejs (website)
• haml
• haml-coffee
• hamlet
• handlebars (website)
• hogan (website)
• htmling
• jade (website)
• jazz
• jqtpl
• JUST
• liquid (website)
• liquor
• lodash (website)
• marko (website)
• mote (website)
• mustache
• nunjucks (website)
• plates
• pug (formerly jade) (website)
• QEJS
• ractive
• razor
• react
• slm
• squirrelly (website)
• swig (maintained fork)
• swig (unmaintained)
• teacup
• templayed
• toffee
• twig
• underscore (website)
• vash
• velocityjs (website)
• walrus (website)
• whiskers

NOTE: If you wish to use template engines other than nunjucks or handlebars, you must install the engines you wish to use: Add them to your package.json dependencies or install globally.