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 through the linter's 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

Usage

Direct usage

Run templates through the linter's verify method like so:

var TemplateLinter = require('ember-template-lint');

var linter = new TemplateLinter();
var template = fs.readFileSync('some/path/to/template.hbs', { encoding: 'utf8' });
var results = linter.verify({ source: template, moduleId: 'template.hbs' });

results will be an array of objects which have the following properties:

• rule - The name of the rule that triggered this warning/error.
• message - The message that should be output.
• line - The line on which the error occurred.
• column - The column on which the error occurred.
• moduleId - The module path for the file containing the error.
• source - The source that caused the error.
• fix - An object describing how to fix the error.

CLI executable

Basic ember-template-lint executable is provided, allowing for easy use within i.e. Git pre-commit/push hooks and development of appropriate plugins for text editors.

Example usage:

# basic usage
./node_modules/.bin/ember-template-lint app/templates/application.hbs

# output errors with source description
./node_modules/.bin/ember-template-lint app/templates/application.hbs --verbose

# multiple file/directory/wildcard paths are accepted
./node_modules/.bin/ember-template-lint app/templates/components/**/* app/templates/application.hbs

# output errors as pretty-printed JSON string
./node_modules/.bin/ember-template-lint app/templates/application.hbs --json

ESLint

If you are using templates inlined into your JS files, you can leverage eslint-plugin-hbs to integrate ember-template-lint into your normal eslint workflow.

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 -->
{{! template-lint-disable }}

<!-- disable bare-strings -->
{{! template-lint-disable bare-strings }}

<!-- disable bare-strings and triple-curlies -->
{{! template-lint-disable bare-strings triple-curlies }}

<!-- enable all rules -->
{{! template-lint-enable }}

<!-- enable bare-strings -->
{{! template-lint-enable bare-strings }}

<!-- enable bare-strings and triple-curlies -->
{{! template-lint-enable bare-strings triple-curlies }}

and to configure rules in the template:

{{! template-lint-configure bare-strings ["ZOMG THIS IS ALLOWED!!!!"] }}

{{! template-lint-configure bare-strings {"whitelist": "(),.", "globalAttributes": ["title"]} }}

The configure instruction can only configure a single rule, and the configuration value must be valid JSON that parses into a configuration for that rule.

These configuration instructions do not modify the rule for the rest of the template, but instead modify it within whatever DOM scope the comment instruction appears.

An instruction will apply to all later siblings and their descendants:

<!-- disable for <p> and <span> and their contents, but not for <div> or <hr> -->
<div>
  <hr>
  {{! template-lint-disable }}
  <p>
    <span>Hello!</span>
  </p>
</div>

An in-element instruction will apply to only that element:

<!-- enable for <p>, but not for <div>, <hr> or <span> -->
<div>
  <hr>
  <p {{! template-lint-enable }}>
    <span>Hello!</span>
  </p>
</div>

An in-element instruction with the -tree suffix will apply to that element and all its descendants:

<!-- configure for <p>, <span> and their contents, but not for <div> or <hr> -->
<div>
  <hr>
  <p {{! template-lint-configure-tree block-indentation "tab" }}>
    <span>Hello!</span>
  </p>
</div>

Note that enabling a rule ({{! template-lint-enable }}) that has been configured in-template ({{! template-lint-configure }}), will restore it to its default configuration rather than the modified in-template configuration for the scope of the {{! template-lint-enable }} instruction.

Configuration Keys

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

• rules -- Object This is an object containing rule specific configuration (see details for each rule below).
• extends -- string|string[] Either a string or an array of strings. Each string allows you to specify an internally curated list of rules (we suggest recommended here).
• pending -- string[] 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.
• ignore -- string[]|glob[] An array of module id's that are to be completely ignored.
• plugins -- (string|Object)[] An array of plugin objects, or strings that resolve to files that export plugin objects. See plugin documentation for more details.

Rules

Current list of rules and deprecations can be found in docs/rules.md.

Defining your own rules

You can define and use your own custom rules using the plugin system. See plugin documentation for more details.

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

0.8.4

• Add new attribute-indentation rule. Examples:

{{! good }}

{{foo-bar baz="bat" derp="qux"}}

{{foo-bar
  baz="bat"
  derp="qux"
}}

{{#foo-bar
  baz="bat"
  derp="qux"
as |foo|}}
  stuff here
{{/foo-bar}}

{{#foo-bar baz="bat" derp="qux" as |foo|}}
  stuff here
{{/foo-bar}}

{{! bad }}

{{foo-bar baz="bat"
  derp="qux"
}}

{{foo-bar
baz="bat"
derp="qux"
}}

{{foo-bar
  baz="bat"
  derp="qux"}}

You can read more about the rule (and configuration) in the documentation.