ember-template-recast

What is ember-template-recast?

ember-template-recast is a tool for programmatically modifying Handlebars templates in Ember.js projects. It provides a way to parse, traverse, and transform templates, making it useful for tasks such as codemods, linting, and automated refactoring.

What are ember-template-recast's main functionalities?

Parsing Templates

This feature allows you to parse a Handlebars template string into an Abstract Syntax Tree (AST). The AST can then be traversed and manipulated.

const recast = require('ember-template-recast');
const template = '<div>{{foo}}</div>';
const ast = recast.parse(template);
console.log(ast);

Transforming Templates

This feature allows you to transform a Handlebars template by providing a transformation function. The example changes all instances of `{{foo}}` to `{{bar}}`.

const recast = require('ember-template-recast');
const template = '<div>{{foo}}</div>';
const transform = function(env) {
  let { builders: b } = env.syntax;
  return {
    MustacheStatement(node) {
      if (node.path.original === 'foo') {
        return b.mustache(b.path('bar'));
      }
    }
  };
};
const output = recast.transform(template, transform);
console.log(output);

Printing Templates

This feature allows you to convert an AST back into a Handlebars template string. This is useful after making transformations to the AST.

const recast = require('ember-template-recast');
const template = '<div>{{foo}}</div>';
const ast = recast.parse(template);
const output = recast.print(ast);
console.log(output);

Other packages similar to ember-template-recast

handlebars

Handlebars is a popular templating engine that allows you to build semantic templates. While it provides the ability to compile and render templates, it does not offer the same level of AST manipulation and transformation capabilities as ember-template-recast.

glimmer-engine

Glimmer is a high-performance rendering engine used in Ember.js. While it provides low-level rendering capabilities and some template compilation features, it does not offer the same high-level API for template transformation and manipulation as ember-template-recast.

README

ember-template-recast

APIs

parse

Used to parse a given template string into an AST. Generally speaking, this AST can be mutated and passed into print (docs below).

const templateRecast = require('ember-template-recast');
const template = `
{{foo-bar
  baz="stuff"
}}
`;
let ast = templateRecast.parse(template);
// now you can work with `ast`

print

Used to generate a new template string representing the provided AST.

const templateRecast = require('ember-template-recast');
const template = `
{{foo-bar
  baz="stuff"
}}
`;
let ast = templateRecast.parse(template);
ast.body[0].hash[0].key = 'derp';

templateRecast.print(ast);

    {{foo-bar
      derp="stuff"
    }}

traverse

Used to easily traverse (and possibly mutate) a given template. Returns the resulting AST and the printed template.

The plugin argument has roughly the following interface:

export interface ASTPluginBuilder {
  (env: ASTPluginEnvironment): ASTPlugin;
}

export interface ASTPluginEnvironment {
  meta?: any;
  syntax: Syntax;
}

export interface ASTPlugin {
  name: string;
  visitor: NodeVisitor;
}

export interface Syntax {
  parse: typeof preprocess;
  builders: typeof builders;
  print: typeof print;
  traverse: typeof traverse;
  Walker: typeof Walker;
}

The list of known builders on the env.syntax.builders are found here

Example:

const templateRecast = require('ember-template-recast');
const template = `
{{foo-bar
  baz="stuff"
}}
`;
let { code } = transform(template, env => {
  let { builders: b } = env.syntax;

  return {
    MustacheStatement() {
      return b.mustache(b.path('wat-wat'));
    },
  };
});

console.log(code); // => {{wat-wat}}

Command Line Usage

ember-template-recast comes with a binary for running a transform across multiple files, similar to jscodeshift.

npm install -g ember-template-recast
ember-template-recast directory/of/templates -t transform.js

Example transform plugin:

module.exports = function({ source, path }, { parse, visit }) {
  const ast = parse(source);

  return visit(ast, env => {
    let { builders: b } = env.syntax;

    return {
      MustacheStatement() {
        return b.mustache(b.path('wat-wat'));
      },
    };
  });
};

Changelog

v1.2.0 (2018-06-26)

:rocket: Enhancement

• #8 Add a binary for running transforms across multiple files. (@lennyburdette)

:bug: Bug Fix

• #9 Ensure parseInt is called with the correct radix.. (@rwjblue)

Committers: 2

• Lenny Burdette (lennyburdette)
• Robert Jackson (rwjblue)