TEMPLATE_ENGINE.md

Template Engine Documentation

This documentation describes the interface between this template and the cli. See that repo for more information.

---

Basic File Annotation

<comment> template[<methods>]

• <comment> A literal file comment. Most are supported.
• template[...] The root identifier for this engine
• [<methods>] Processing methods.

1. Using a .template file

Including a .template file in any directory automatically includes all files and its descendants. Annotating the file further allows for control. (See the methods api below for avail. annotations).

2. Advanced annotation for .json files

Because .json files do not support commenting, an annotation of "_template": "<REGULAR_ANNOTATION>" is required. Further, .json files have additional methods associated with them. See the Methods API for details.

---

Methods API

---

tags(<tag_name>,...)

Allows for grouping related templates / operations. These tags can be dynamically applied or ignored at run-time. Any valid string can be used as a tag. See the CLI docs for more information about processing tags. NOTE: While you can leave the tag method off, you lose all control via the cli and that's not recommended!

replace(<key>:<value>,...)

Replaces a single matching <key> with a <value> separated by a : on the line below the annotation. Supports an array of <key>:<value> comma separated key / value pairs.

replace_all(<key>:<value>,...)

Replaces every occurance of a <key> with a <value> separated by a :. As with the single replace version, multiple vars can be defined when comma separated. Global vars are avail, see below

ignore(<path>,...)

When used in a .template file, specified paths will be ignored from the recursive copying of templates. Tagging this file subsequently tags all descendents, however, individual children can include tags. The tags defined in a parent .template file will still apply. This method accepts basic regex such as * or !

json(<keys_to_copy>) (json files only)

JSON files allow for the copying of specific keys as opposed to the whole file to prevent potential issues with package versioning in package.json files or other version specific configurations.

---

Global Vars

${CUSTOM_VAR}

Replace methods above have access to global vars. These vars are unique to the project and are configured in the CLI. Currently ${app_name} is the only avail one in this template repo.

Examples:

basic usage:

// template[tags(mytag)]
import React from 'react'

...all the code

alternate comment examples

<!-- template[tags(foo,bar)] ->
...code

/* template[replace(myapp:${var_from_cli_config})] */
...code

replacing a single variable

function foo(bar: string) {
  // template[replace(APP_NAME:${app_name})]
  const app = "APP_NAME"
  return app
}

replacing many variables

// template[replace_all(i-will-be-replaced:${app_name})]

const Component = () => {
  return <div>Hello from i-will-be-replaced<div>
}

const App = () => {
  return <div>I want to be replaced too! i-will-be-replaced<div>
}

An example with json only copying a single key while also replacing vars

{
  "_template": "template[tags(config),json(short),replace_all(pot:${app_name})]",
  "iama": "little",
  "tea": "pot",
  "short": {
    "and": "stout"
  }
}