or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ast-plugin-system.mdbroccoli-plugin.mdember-cli-integration.mdindex.mdtemplate-compilation.md
tile.json

index.mddocs/

Ember CLI HTMLBars

Ember CLI HTMLBars is an Ember CLI addon that provides HTMLBars template compilation functionality for Ember.js applications. It serves as the core template processing engine that transforms HTMLBars templates into JavaScript code, enabling features like Handlebars template syntax, custom AST transformations, and template precompilation.

Package Information

  • Package Name: ember-cli-htmlbars
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install ember-cli-htmlbars
  • Ember CLI Integration: Automatically included in Ember applications

Core Imports

For testing and component template compilation:

import { hbs } from 'ember-cli-htmlbars';

For Broccoli build integration:

const TemplateCompilerPlugin = require('ember-cli-htmlbars').TemplateCompilerPlugin;

Basic Usage

Template Testing Helper

import { hbs } from 'ember-cli-htmlbars';
import { render } from '@ember/test-helpers';

// In tests - tagged template literal
await render(hbs`<MyComponent @value={{42}} />`);

// With explicit options
const template = hbs('<p>{{this.greeting}}</p>', { 
  moduleName: 'components/greeting.hbs' 
});

Ember CLI Addon Integration

// In ember-cli-build.js
module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    'ember-cli-htmlbars': {
      templateCompilerPath: 'path/to/custom-template-compiler.js'
    }
  });
  return app.toTree();
};

Architecture

Ember CLI HTMLBars is built around several key components:

  • Template Compilation: Core Broccoli plugin for transforming .hbs files to JavaScript modules
  • AST Plugin System: Extensible architecture for custom template transformations
  • Babel Integration: Inline precompilation for hbs tagged template literals
  • Colocation Support: Automatic template association with component files
  • Caching System: Persistent caching with dependency invalidation
  • Ember CLI Integration: Full integration with Ember's build pipeline and addon system

Capabilities

Template Compilation

Core template compilation functionality that transforms HTMLBars template files (.hbs) into JavaScript modules. Handles both standalone template files and colocated component templates.

function hbs(template: string, options?: PrecompileOptions): TemplateFactory;
function hbs(tagged: TemplateStringsArray): TemplateFactory;

interface PrecompileOptions {
  moduleName?: string;
  parseOptions?: {
    srcName?: string;
  };
}

class TemplateFactory {
  private readonly [Data]: 'template-factory';
}

Template Compilation

Broccoli Plugin

Broccoli plugin for build-time template processing, providing persistent caching and incremental builds. Used internally by Ember CLI and available for custom build pipelines.

class TemplateCompilerPlugin extends BroccoliFilter {
  constructor(inputTree: BroccoliTree, options?: TemplateCompilerOptions): TemplateCompilerPlugin;
  processString(string: string, relativePath: string): string;
  getDestFilePath(relativePath: string): string | undefined;
}

Broccoli Plugin

AST Plugin System

Extensible system for registering custom HTMLBars AST transformations. Supports both simple transforms and dependency-aware plugins with caching strategies.

interface ASTPluginWrapper {
  name: string;
  plugin: ASTPluginBuilder;
  dependencyInvalidation?: boolean;
  cacheKey?: () => string;
  baseDir?: () => string;
  parallelBabel?: object;
}

AST Plugin System

Ember CLI Addon Interface

Complete Ember CLI addon interface providing template preprocessing, Babel plugin integration, and project configuration. Handles automatic setup and integration with the Ember build pipeline.

interface EmberCLIHTMLBarsAddon {
  transpileTree(inputTree: BroccoliTree, htmlbarsOptions?: object): BroccoliTree;
  setupPreprocessorRegistry(type: string, registry: PreprocessorRegistry): void;
  htmlbarsOptions(): HTMLBarsOptions;
  templateCompilerPath(): string;
}

Ember CLI Integration

Types

interface HTMLBarsOptions {
  isHTMLBars: boolean;
  EmberENV: object;
  templateCompiler: object;
  templateCompilerPath: string;
  pluginNames: string[];
  plugins: {
    ast: ASTPlugin[];
  };
  dependencyInvalidation: boolean;
  pluginCacheKey: string[];
}

interface ASTPluginEnvironment {
  moduleName: string;
  meta: object;
}

interface ASTPlugin {
  name: string;
  visitor: object;
}

// Broccoli types
interface BroccoliTree {
  // Opaque Broccoli tree type
}

interface BroccoliFilter {
  // Base class for Broccoli plugins
}

// Ember CLI types  
interface PreprocessorRegistry {
  // Ember CLI preprocessor registry interface
}

interface TemplateCompilerOptions {
  persist?: boolean;
  isProduction?: boolean;
  templateCompiler?: object;
  plugins?: {
    ast?: ASTPlugin[];
  };
  pluginNames?: string[];
  dependencyInvalidation?: boolean;
}