temples

    2.1.1 • Public • Published

    Temples


    🕍

    Automatically generate code from predefined templates. No boilerplate.

    Boilerplate coding is tedious. Temples automates the process by giving you the ability to define Handlebars templates, target paths, and the CLI commands to automatically generate the code. You can create new files or insert into existing ones.


    Example of Temples CLI

    Feedback and stars welcomed! :)


    Getting Started



    Installation

    # Install globally
    npm install [-g] temples
    
    # Or, in your project
    npm install --save-dev temples


    Usage

    Temples reads from a .temples.yaml configuration file. Refer to Configuration below to create your own configuration file before running temples.

    You can run temples by specifying the generator command and props, or invoke a CLI step by step interface where you can input these parameters.

    # Invoke CLI interface
    temples
    
    # Or, directly specify generator and value for each prop
    temples [generator] --[prop]=[value] ...
    
    # Read more in the manual
    temples -h


    Configuration

    generators

    Required. Temples will throw error if undefined.

    In your .temples.yaml file, specify the generators object. This lists all available generators and what each does, either creating new files or inserting code into existing files.

    # .temples.yaml
    
    generators:
      # Give your command a name
      [command]:
        # Documentation for this command will
        # be shown during CLI interface
        doc: ...
    
        files: ...
        inserts: ...


    files

    Generate new files given a target path, and an optional template path. If template is given, temples will use the contents of that template, compile it with given props, and output to target path.

    # .temples.yaml
    
    generators:
      new-component:
        files:
          # Use `component.hbs` and create `index.js`
          - template: component.hbs
            target: index.js
    
          # Create empty file at `index.js`
          - target: index.js
    
          # Compile with `name` and create
          # file at `[component_name]/index.js`
          - target: '{{ name }}/index.js'


    inserts

    Insert code into targeted files. Temples uses user defined regex to find tags in targeted files and replace them with the parsed content. File comments are the best ways to do this:

    /* components/index.js */
    
    // temples(import {{ name }} from './{{ name }}';)
    import Button from './Button';
    # .temples.yaml
    
    # File extension to ECMAScript regex pattern
    #
    # The first regex capture group is the
    # template for the insert
    regex:
      js: '\/\/ temples\((.+)\)'
    
    generators:
      new-component:
        inserts:
          # Insert into `components/index.js`
          - target: components/index.js
    
          # Insert into `components/[component_name]/index.js`
          - target: 'components/{{ name }}/index.js'

    Here's a great playground tool for finding the right regex pattern.



    base

    Specify the base paths for templates, files, or inserts. base can be specified and overridden in the root configuration file or the generator command's configuration.

    # .temples.yaml
    
    # Find templates, files, and inserts
    # under `dir/`
    base: dir
    
    generators:
      new-component:
        # Override to be `dir/subdir/`
        base: dir/subdir
    
        # Find templates in `dir/templates`
        # Target files and inserts in `dir/targets`
        base:
          templates: dir/templates
          target: dir/targets
    
        # Find templates in `dir/templates`
        # Target files in `dir/targets/files`
        # Target inserts in `dir/targets/inserts`
        base:
          templates: dir/templates
          target:
            files: dir/targets/files
            inserts: dir/targets/inserts


    default

    Default prop values if not provided in CLI.

    If there is no default provided and user doesn't specify value, Handlebars compiles undefined props to empty string.

    # .temples.yaml
    
    default:
      name: 'NewComponent'
    
    generators:
      new-component:
        # Override default in root level
        default:
          name: 'NewestComponent'
        ...


    props

    Specify props that should be prompted for in the CLI interface. It's not optimal for temples to search through all props available in templates. You can specify which props to prompt for with this key.

    # .temples.yaml
    
    generators:
      new-component:
        # Ask user for `name` and `directory`
        props: [name, directory]
    
        # In YAML, this is the same
        props:
        - name
        - directory
    
        # Provide documentation for each prop
        # during CLI interface
        props:
        - name: name
          doc: Name of component
        - name: directory
          doc: Directory to place component in


    position

    Position to insert output to. This is relative to the regex tag in the target file. Default position is below. The most specific position will be used.

    # .temples.yaml
    
    position: above | below | right | left
    
    generators:
      new-component:
        position: above | below | right | left
    
        inserts:
          - target: components/index.js
            position: above | below | right | left


    Handlebars Helpers

    Temples uses Handlebars templating engine, and temples has some built-in helpers.

    camel-case

    Convert into camelCase.

    {{ camel name }}
    
    # Input: { name: "BigButton" }
    bigButton

    kebab-case

    Convert into kebab-case

    {{ kebab-case name }}
    
    # Input: { name: "bigButton" }
    big-button

    snake-case

    Convert into snake_case

    {{ snake-case name }}
    
    # Input: { name: "big-button" }
    big_button

    upper-case

    Convert into UPPER CASE

    {{ upper-case name }}
    
    # Input: { name: "big-button" }
    BIG BUTTON

    lower-case

    Convert into lower case

    {{ lower-case name }}
    
    # Input: { name: "big-button" }
    big button

    title-case

    Convert into TitleCase

    {{ title-case name }}
    
    # Input: { name: "big_button" }
    BigButton


    Customizing Handlebars

    The built-in helpers might not be enough for your use case. You can customize the Handlebars instance temples uses by specifying a path to a JavaScript file that configures Handlebars.

    Runtime Options

    Use the given handlebars instance to change its settings. See the Handlebars runtime documentation.

    Compile Options

    Return an object to customize the compile options for Handlebars. See the Handlebars compile options.

    # .temples.yaml
    
    handlebars: configureHandlebars.js
    // configureHandlebars.js
    
    module.exports = (handlebars) => {
      handlebars.registerHelper('replace', (v) => {
        return v.replace(' ', '-');
      });
    
      return {
        noEscape: false,
      };
    };


    Caveats

    Naming Conflicts

    If a variable conflicts with a helper name (e.g. {{ title }}), Handlebars will treat it as a helper instead of a variable. You can namespace the variable with this or ./ to avoid naming conflicts.

    {{ this.title }}

    Escaping Handlebars Syntax

    Sometimes you need Handlebars to ignore parsing a prop. For example, if you're generating a file from a twig template, Handlebars might parse {{ example }} unintentionally.

    You can leave it as it is by escaping:

    \{{ example }}


    Example

    Check out a documented example here.



    License

    Copyright © 2020 - Present, Gino Jacob. MIT License.

    Install

    npm i temples

    DownloadsWeekly Downloads

    16

    Version

    2.1.1

    License

    ISC

    Unpacked Size

    34.7 kB

    Total Files

    14

    Last publish

    Collaborators

    • gvjacob