ember-template-lint

7.9.3 verified Fri May 01 auth: no javascript

Linter for Ember or Handlebars templates, version 7.9.3. Released regularly with monthly minor/patch updates. It provides over 100 built-in rules covering accessibility, styling, and best practices, with presets for recommended, stylistic, and a11y. Key differentiator: first-class integration with Ember projects, auto-fix support, and plugin architecture. Unlike generic HTML linters, it understands Handlebars syntax and Ember-specific patterns like components and modifiers. Requires Node ^18.18.0 || >=20.9.0.

Common errors

error Cannot find module 'ember-template-lint' ↓

cause Package not installed or path resolution issue.

fix

Run npm install --save-dev ember-template-lint or check your node_modules.

error Rule 'no-bare-strings' is not configured. ↓

cause Rule not enabled in .template-lintrc.js or used outside a project.

fix

Add 'no-bare-strings': true to rules in config file.

error Error: EMFILE: too many open files ↓

cause Max file descriptors reached when linting many files.

fix

Increase file descriptor limit (e.g., ulimit -n 4096) or lint fewer files at once.

error The `config` option must be an object, not a string ↓

cause Passing deprecated string path to Linter constructor.

fix

Load config with require or use getConfig and pass the object.

Warnings

breaking Node.js versions <18.18.0 or <20.9.0 are no longer supported as of v7.0.0. ↓

fix Upgrade Node.js to ^18.18.0 || ^20.9.0 || >=21.1.0.

breaking The `config` option in the Linter constructor no longer accepts a file path string; must be an object. ↓

fix Pass config object directly, or use `getConfig` to load from file.

deprecated Rule `no-unnecessary-curly-strings` deprecated in favor of `no-curly-component-invocation`. ↓

fix Replace rule name in config.

gotcha `Linter.verify()` is async; forgetting `await` results in a Promise object. ↓

fix Use `await linter.verify(...)`.

gotcha Rules with the same name from different plugins may conflict; later plugin overrides earlier. ↓

fix Ensure unique rule names or use plugin namespacing.

deprecated The `--json` flag is deprecated in favor of `--format=json` ↓

fix Use `ember-template-lint --format=json`.

Install

npm install ember-template-lint

yarn add ember-template-lint

pnpm add ember-template-lint

Imports

Linter
wrong
```
const Linter = require('ember-template-lint')
```
correct
```
import Linter from 'ember-template-lint'
```
Default export; ESM import preferred. CommonJS require is still supported for backward compatibility.

Linter

wrong

const Linter = require('ember-template-lint').Linter

correct

const { Linter } = require('ember-template-lint')

CommonJS destructured import works; direct property access also works but less idiomatic.

getConfig

import { getConfig } from 'ember-template-lint'

Utility to load and merge config files.

FIXABLE_RULES

import { FIXABLE_RULES } from 'ember-template-lint'

List of rule names that support auto-fix.

Quickstart

Setup config file, run CLI, use programmatic API to lint and fix a template.

// Create .template-lintrc.js
'use strict';

module.exports = {
  extends: 'recommended',
  rules: {
    'no-bare-strings': true,
  },
};

// Run lint via CLI
// npx ember-template-lint .

// Or use programmatic API
import Linter from 'ember-template-lint';

const linter = new Linter();
const results = await linter.verify({
  source: '<div>A bare string</div>',
  filePath: 'app/templates/application.hbs',
  config: {
    rules: {
      'no-bare-strings': true,
    },
  },
});

console.log(results);
// [
//   {
//     rule: 'no-bare-strings',
//     severity: 2,
//     filePath: 'app/templates/application.hbs',
//     message: 'Non-translated string used',
//     line: 1,
//     column: 5
//   }
// ]

// Auto-fix
import { verifyAndFix } from 'ember-template-lint';
const fixed = await verifyAndFix({
  source: '<div>A bare string</div>',
  filePath: 'app/templates/application.hbs',
  config: {
    rules: {
      'no-bare-strings': 'fix',
    },
  },
});