Skip to content

ember-cli/ember-cli-htmlbars

Folders and files

NameName
Last commit message
Last commit date

Latest commit

671b395 · Dec 23, 2023
Dec 23, 2023
Dec 21, 2023
Dec 22, 2023
Dec 22, 2023
Jul 31, 2018
Dec 23, 2023
Jul 31, 2018
Dec 21, 2023
Dec 21, 2023
Dec 21, 2023
Dec 21, 2023
Feb 14, 2015
Feb 13, 2015
Dec 21, 2023
Dec 21, 2023
Dec 21, 2023
Dec 21, 2023
Oct 14, 2021
Dec 21, 2023
Aug 8, 2023
Jul 21, 2015
Apr 16, 2016
Dec 23, 2023
Feb 24, 2021
Oct 14, 2021
Dec 22, 2023
Dec 4, 2019
Dec 21, 2023
Dec 22, 2023

Repository files navigation

Ember CLI HTMLBars

Build Status

Compatibility

  • Ember.js v4.12 or above
  • Ember CLI v4.12 or above
  • @embroider/compat 3.4.3 or above (optional)
  • Node.js v18 or above

Adding Custom Plugins

You can add custom plugins to be used during transpilation of the addon/ or addon-test-support/ trees of your addon (or the app/ and tests/ trees of an application) by registering a custom AST transform.

var SomeTransform = require('./some-path/transform');

module.exports = {
  name: 'my-addon-name',

  included: function() {
    // we have to wrap these in an object so the ember-cli
    // registry doesn't try to call `new` on them (new is actually
    // called within htmlbars when compiling a given template).
    this.app.registry.add('htmlbars-ast-plugin', {
      name: 'some-transform',
      plugin: SomeTransform
    });
    
    this._super.included.apply(this, arguments);
  }
};

Options for registering a plugin

  • name - String. The name of the AST transform for debugging purposes.
  • plugin - A function of type ASTPluginBuilder.
  • dependencyInvalidation - Boolean. A flag that indicates the AST Plugin may, on a per-template basis, depend on other files that affect its output.
  • cacheKey - function that returns any JSON-compatible value - The value returned is used to invalidate the persistent cache across restarts, usually in the case of a dependency or configuration change.
  • baseDir - () => string. A function that returns the directory on disk of the npm module for the plugin. If provided, a basic cache invalidation is performed if any of the dependencies change (e.g. due to a npm install/upgrade).

Implementing Dependency Invalidation in an AST Plugin

Plugins that set the dependencyInvalidation option to true can provide function for the plugin of type ASTDependencyPlugin as given below.

Note: the plugin function is invoked without a value for this in context.

import {ASTPluginBuilder, ASTPlugin} from "@glimmer/syntax/dist/types/lib/parser/tokenizer-event-handlers";

export type ASTDependencyPlugin = ASTPluginWithDepsBuilder | ASTPluginBuilderWithDeps;

export interface ASTPluginWithDepsBuilder {
  (env: ASTPluginEnvironment): ASTPluginWithDeps;
}

export interface ASTPluginBuilderWithDeps extends ASTPluginBuilder {
  /**
   * @see {ASTPluginWithDeps.dependencies} below.
   **/
  dependencies(relativePath): string[];
}

export interface ASTPluginWithDeps extends ASTPlugin {
  /**
   * If this method exists, it is called with the relative path to the current
   * file just before processing starts. Use this method to reset the
   * dependency tracking state associated with the file.
   */
  resetDependencies?(relativePath: string): void;
  /**
   * This method is called just as the template finishes being processed.
   *
   * @param relativePath {string} A relative path to the file that may have dependencies.
   * @return {string[]} paths to files that are a dependency for the given
   * file. Any relative paths returned by this method are taken to be relative
   * to the file that was processed.
   */
  dependencies(relativePath: string): string[];
}

Custom Template Compiler

You can still provide a custom path to the template compiler (e.g. to test custom template compiler tweaks in an application) by:

// ember-cli-build.js

module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    'ember-cli-htmlbars': {
      templateCompilerPath: `some_path/to/ember-template-compiler.js`,
    }
  });
};

Using as a Broccoli Plugin

var HtmlbarsCompiler = require('ember-cli-htmlbars');

var templateTree = new HtmlbarsCompiler('app/templates', {
  isHTMLBars: true,

  // provide the templateCompiler that is paired with your Ember version
  templateCompiler: require('./bower_components/ember/ember-template-compiler')
});