ember-template-lint will lint your template and return error results.
For example, given the rule no-bare-strings
is enabled, this template would be
in violation:
When ran through the linter's verify
method, we would have a single result indicating that
the no-bare-strings
rule found an error.
This addon is installed by default with new Ember apps, so check your package.json before installing to see if you need to install it.
To install ember-template-lint
npm install --save-dev ember-template-lint
Node.js 10 || >=12
is required.
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.
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.
Ensure you wrap all glob patterns in quotes so that it won't be interpreted by the CLI.
./node_modules/.bin/ember-template-lint app/templates/**
(this will expand all paths in app/templates) and./node_modules/.bin/ember-template-lint "app/templates/**"
(this will pass the glob to ember-template-lint and not interpret the glob).
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
# ignore warnings / only report errors
./node_modules/.bin/ember-template-lint "app/templates/application.hbs" --quiet
# define custom config path
./node_modules/.bin/ember-template-lint "app/templates/application.hbs" --config-path .my-template-lintrc.js
# read from stdin
./node_modules/.bin/ember-template-lint --filename app/templates/application.hbs < app/templates/application.hbs
# print list of formated rules for use with `pending` in config file
./node_modules/.bin/ember-template-lint "app/templates/application.hbs" --print-pending
# specify custom ignore pattern `['**/dist/**', '**/tmp/**', '**/node_modules/**']` by default
./node_modules/.bin/ember-template-lint "/tmp/template.hbs" --ignore-pattern "**/foo/**" --ignore-pattern "**/bar/**"
# disable ignore pattern entirely
./node_modules/.bin/ember-template-lint "/tmp/template.hbs" --no-ignore-pattern
# running a single rule without options
./node_modules/.bin/ember-template-lint --no-config-path app/templates --rule 'no-implicit-this:error'
# running a single rule with options
./node_modules/.bin/ember-template-lint --no-config-path app/templates --rule 'no-implicit-this:["error", { "allow": ["some-helper"] }]'
# specify a config object to use instead of what exists locally
./node_modules/.bin/ember-template-lint --config '{ "rules": { "no-implicit-this": { "severity": 2, "config": true } } }' test/fixtures/no-implicit-this-allow-with-regexp/app/templates
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.
Name | Description | |
---|---|---|
✅ | recommended | enables the recommended rules |
🚗 | octane | extends the recommended preset by enabling Ember Octane rules |
👗 | stylistic | enables stylistic rules for those who aren't ready to adopt ember-template-lint-plugin-prettier (including stylistic rules that were previously in the recommended preset in ember-template-lint v1) |
You can turn on specific rules by toggling them in a
.template-lintrc.js
file at the base of your project, or at a custom relative
path which may be identified using the CLI:
module.exports = {
extends: 'recommended',
rules: {
'no-bare-strings': true
}
}
This extends from the builtin recommended configuration (lib/config/recommended.js),
and also enables the no-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: {
'no-bare-strings': ['ZOMG THIS IS ALLOWED!!!!']
}
};
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 suggestrecommended
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 thispending
listing and slowly work through them, while at the same time ensuring that new templates added to the project pass all defined rules.- You can generate this list with the:
./node_modules/.bin/ember-template-lint * --print-pending
- You can generate this list with the:
ignore
--string[]|glob[]
An array of module id's that are to be completely ignored. See ignore documentation for more details.plugins
--(string|Object)[]
An array of plugin objects, or strings that resolve to files that export plugin objects. See plugin documentation for more details.overrides
--Array
An array of overrides that would allow overriding of specific rules for user specified files/folders. See overrides documentation for more details.
Each rule can have its own severity level which can be a string or could be the first element of the array that contains the custom rule configuration.
Supported severity levels are off
, warn
, error
.
You can define a severity level directly on the rule:
Eg: 'no-bare-strings': 'warn'
OR
If your rule has a custom configuration, and you want to define the severity level you would need to add the severity
as the first element of the array.
Eg:
{
"no-implicit-this": ['warn', { "allow": [ "fooData" ] }
}
Current list of rules and deprecations can be found in docs/rules.md.
It is also possible to disable specific rules (or all rules) in a template itself:
and to configure rules in the template:
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:
An in-element instruction will apply to only that element:
An in-element instruction with the -tree
suffix will apply to that element and all its descendants:
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.
You can define and use your own custom rules using the plugin system. See plugin documentation for more details.
It is possible to share a config (extends
) or plugin (custom rules) across projects. See ember-template-lint-plugin-peopleconnect for an example.
The semver policy for this addon can be read here: semver policy.
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
See the Contributing Guidelines for information on how to help out.