ember-template-lint

What is ember-template-lint?

ember-template-lint is a linting tool for Ember.js templates. It helps developers maintain consistent coding styles, catch potential errors, and enforce best practices in Handlebars templates.

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

Linting Templates

This feature allows you to lint your Handlebars templates to ensure they follow specific rules. For example, the 'no-bare-strings' rule prevents the use of bare strings in templates, encouraging the use of translation helpers instead.

module.exports = { 'no-bare-strings': true };

Custom Rules

You can define custom linting rules to enforce specific coding standards within your project. In this example, the 'no-inline-styles' rule is set to 'error' severity, which will flag any inline styles in templates as errors.

module.exports = { rules: { 'no-inline-styles': { severity: 'error' } } };

Configuration File

You can extend from predefined configurations to quickly set up linting rules. The 'recommended' configuration includes a set of rules that are generally considered best practices for Ember.js templates.

module.exports = { extends: 'recommended' };

Other packages similar to ember-template-lint

eslint

ESLint is a widely-used linting tool for JavaScript. It helps developers find and fix problems in their JavaScript code. While ESLint focuses on JavaScript, ember-template-lint is specifically designed for Handlebars templates in Ember.js.

stylelint

Stylelint is a linter for CSS and other stylesheets. It helps enforce consistent conventions and avoid errors in stylesheets. Like ember-template-lint, it is highly configurable, but it focuses on styles rather than Handlebars templates.

ember-cli-template-lint

ember-cli-template-lint is an older package that integrates template linting into the Ember CLI build process. It has been largely superseded by ember-template-lint, which offers more features and better integration.

README

ember-template-lint

ember-template-lint will lint your template and return error results. This is commonly used through ember-cli-template-lint which adds failing lint tests for consuming ember-cli applications.

For example, given the rule bare-strings is enabled, this template would be in violation:

{{! app/components/my-thing/template.hbs }}
<div>A bare string</div>

When ran throught the linters verify method we would have a single result indicating that the bare-strings rule found an error.

Install

To install ember-template-lint

npm install --save-dev ember-template-lint

Configuration

Project Wide

You can turn on specific rules by toggling them in a .template-lintrc.js file at the base of your project:

module.exports = {
  extends: 'recommended',

  rules: {
    'bare-strings': true
  }
}

This extends from the builtin recommended configuration (lib/config/recommended.js), and also enables the bare-strings rule (see here).

Using this mechanism allows you to extend from the builtin, and modify specific rules as needed.

Some rules also allow setting additional configuration, for example if you would like to configure some "bare strings" that are allowed you might have:

module.exports = {
  rules: {
    'bare-strings': ['ZOMG THIS IS ALLOWED!!!!']
  }
};

Per Template

It is also possible to disable specific rules (or all rules) in a template itself:

{{! disable all rules for this template }}
<!-- template-lint disable=true -->

{{! disable specific rules for this template }}
<!-- template-lint bare-strings=false -->

It is not currently possible to change rule configuration in the template.

Configuration Keys

The following properties are allowed in the root of the .template-lintrc.js configuration file:

• rules -- This is an object containing rule specific configuration (see details for each rule below).
• extends -- This is a string that allows you to specify an internally curated list of rules (we suggest recommended here).
• pending -- An array of module id's that are still pending. The goal of this array is to allow incorporating template linting into an existing project, without changing every single template file. You can add all existing templates to this pending listing and slowly work through them, while at the same time ensuring that new templates added to the project pass all defined rules.

Rules

bare-strings

In order to be able to internationalize your application, you will need to avoid using plain strings in your templates. Instead, you would need to use a template helper specializing in translation (ember-i18n and ember-intl are great projects to use for this).

This rule forbids the following:

<h2>Some string here!</h2>

The following values are valid configuration:

• boolean -- true for enabled / false for disabled
• array -- an array of whitelisted strings
• object -- An object with the following keys:
  • whitelist -- An array of whitelisted strings
  • globalAttributes -- An array of attributes to check on every element.
  • elementAttributes -- An object whose keys are tag names and value is an array of attributes to check for that tag name.

When the config value of true is used the following configuration is used:

• whitelist - (),.&+-=*/#%!?:[]{}
• globalAttributes - title
• elementAttributes - { img: ['alt'], input: ['placeholder'] }

block-indentation

Good indentation is crucial for long term maintenance of templates. For example, having blocks misaligned is a common cause of logic errors...

This rule forbids the following examples:

  {{#each foo as |bar}}

    {{/each}}

  <div>
  <p>{{t "greeting"}}</p>
  </div>

<div>
  <p>{{t 'Stuff here!'}}</p></div>

The following values are valid configuration:

• boolean -- true indicates a 2 space indent, false indicates that the rule is disabled.
• numeric -- the number of spaces to require for indentation
• "tab" -- To indicate tab style indentation (1 char)

html-comments

Html comments in your templates will get compiled and rendered into the DOM at runtime. Instead you can annotate your templates using Handlebars comments, which will be stripped out when the template is compiled and have no effect at runtime.

This rule forbids the following:

<!-- comment goes here -->

but allows the following:

{{!-- comment goes here --}}

Html comments containing linting instructions such as:

<!-- template-lint bare-strings=false -->

are of course allowed (and since the linter strips them during processing, they will not get compiled and rendered into the DOM regardless of this rule).

triple-curlies

Usage of triple curly braces to allow raw HTML to be injected into the DOM is large vector for exploits of your application (especially when the raw HTML is user controllable ). Instead of using {{{foo}}}, you should use appropriate helpers or computed properties that return a SafeString (via Ember.String.htmlSafe generally) and ensure that user supplied data is properly escaped.

This rule forbids the following:

{{{foo}}}

nested-interactive

Usage of nested interactive content can lead to UX problems, accessibility problems, bugs and in some cases to DOM errors. You should not put interactive content elements nested inside other interactive content elements. Instead using nested interactive content elements you should separate them and put them one after the other.

This rule forbids the following:

<button type="button">
  Click here and <a href="/">go to home here</a>
</button>

The following values are valid configuration:

• boolean -- true indicates all whitelist test will run, false indicates that the rule is disabled.
• array -- an array of whitelisted tests as the following

Whitelist of option in the configuration (are tags name or element attributes):

• button
• details
• embed
• iframe
• img
• input
• object
• select
• textarea
• tabindex

Deprecations

deprecated-each-syntax

In Ember 2.0, support for using the in form of the {{#each}} helper has been removed.

For example, this rule forbids the following:

{{{#each post in posts}}}
  <li>{{post.name}}</li>
{{/each}}

Instead, you should write the template as:

{{#each posts as |post|}}
  <li>{{post.name}}</li>
{{/each}}

More information is available at the Deprecation Guide.

self-closing-void-elements

HTML has no self-closing tags. The HTML 5 parser will ignore self-closing tag in the case of void elements (tags that shouldn't have a closing tag). Although the parser will ignore it's unnecessary and can lead to confusing with SVG/XML code.

This rule forbids the following:

<img src="http://emberjs.com/images/ember-logo.svg" alt="ember" />
<hr/>

Instead, you should write the template as:

<img src="http://emberjs.com/images/ember-logo.svg" alt="ember">
<hr>

The following values are valid configuration:

• boolean -- true for enabled / false for disabled

Contributing

A few ideas for where to take this in the future:

• The list of rules should be configurable
• This addon should use a test printer shared with jshint, eslint and jscs addons
• A command-line version of the linter should be provided so IDEs and editors can provide feedback to devs during development

Installation

• git clone this repository
• npm install

Running Tests

• npm test

Changelog

v0.5.8

• Fix various issues with block-indentation rule:
  • Ensure that usage of whitespace control in end block does not trigger an error. Before this: {{#if foo}}{{~/if}} would error.
  • Validate indentation for block inverse (aka {{else}}).