Skip to content

Linter for Ember or Handlebars templates

License

Notifications You must be signed in to change notification settings

tstewart15/ember-template-lint

Β 
Β 

Repository files navigation

ember-template-lint

npm version Build Status

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:

{{!-- 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 no-bare-strings rule found an error.

Install

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.

Usage

Direct usage

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

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

let linter = new TemplateLinter();
let template = fs.readFileSync('some/path/to/template.hbs', {
  encoding: 'utf8',
});
let 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.

Ensure you wrap all glob patterns in quotes so that it won't be interpreted by the CLI. yarn ember-template-lint app/templates/** (this will expand all paths in app/templates) and yarn ember-template-lint "app/templates/**" (this will pass the glob to ember-template-lint and not interpret the glob).

Important note for those running ember-template-lint in Github Actions: There is an additional printer always used for Github Actions, if you'd like to disable it set the DISABLE_GITHUB_ACTIONS_ANNOTATIONS env var to true.

Example usage:

# basic usage
yarn ember-template-lint "app/templates/application.hbs"

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

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

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

# ignore warnings / only report errors
yarn ember-template-lint "app/templates/application.hbs" --quiet

# define custom config path
yarn ember-template-lint "app/templates/application.hbs" --config-path .my-template-lintrc.js

# read from stdin
yarn ember-template-lint --filename app/templates/application.hbs < app/templates/application.hbs

# print list of formatted rules for use with `pending` in config file
yarn ember-template-lint "app/templates/application.hbs" --print-pending

# specify custom ignore pattern `['**/dist/**', '**/tmp/**', '**/node_modules/**']` by default
yarn ember-template-lint "/tmp/template.hbs" --ignore-pattern "**/foo/**" --ignore-pattern "**/bar/**"

# disable ignore pattern entirely
yarn ember-template-lint "/tmp/template.hbs" --no-ignore-pattern

# running a single rule without options
yarn ember-template-lint --no-config-path app/templates --rule 'no-implicit-this:error'

# running a single rule with options
yarn ember-template-lint --no-config-path app/templates --rule 'no-implicit-this:["error", { "allow": ["some-helper"] }]'

# running a single rule, disabling inline configuration
yarn ember-template-lint --no-config-path app/templates --rule 'no-implicit-this:error' --no-inline-config

# specify a config object to use instead of what exists locally
yarn ember-template-lint --config '{ "rules": { "no-implicit-this": { "severity": 2, "config": true } } }' test/fixtures/no-implicit-this-allow-with-regexp/app/templates

# disable Github Actions custom printer (only relevant when running in Github Actions)
DISABLE_GITHUB_ACTIONS_ANNOTATIONS=true yarn ember-template-lint "app/templates/application.hbs"

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, 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!!!!'],
  },
};

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.
    • You can generate this list with the: yarn ember-template-lint * --print-pending
  • 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.

Presets

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)

Rules

Each rule has emojis denoting:

  • what configuration it belongs to
  • πŸ”§ if some problems reported by the rule are automatically fixable by the --fix command line option
Rule ID
attribute-indentation
πŸ‘— block-indentation
builtin-component-arguments
deprecated-each-syntax
deprecated-inline-view-helper
βœ… deprecated-render-helper
πŸ‘— eol-last
πŸ”§ inline-link-to
πŸ‘— linebreak-style
βœ… link-href-attributes
βœ…πŸ”§ link-rel-noopener
modifier-name-case
βœ… no-abstract-roles
πŸ”§ no-accesskey-attribute
πŸš— no-action
no-action-modifiers
βœ… no-args-paths
no-arguments-for-html-elements
πŸ”§ no-aria-hidden-body
βœ… no-attrs-in-components
no-bare-strings
no-block-params-for-html-elements
πŸš— no-curly-component-invocation
βœ… no-debugger
no-down-event-binding
βœ… no-duplicate-attributes
no-duplicate-id
no-duplicate-landmark-elements
no-element-event-actions
βœ… no-extra-mut-helper-argument
no-forbidden-elements
no-heading-inside-button
βœ… no-html-comments
πŸš— no-implicit-this
βœ… no-index-component-invocation
βœ… no-inline-styles
βœ… no-input-block
βœ… no-input-tagname
no-invalid-block-param-definition
βœ… no-invalid-interactive
βœ… no-invalid-link-text
no-invalid-link-title
βœ… no-invalid-meta
βœ… no-invalid-role
no-link-to-tagname
βœ… no-log
πŸ”§ no-model-argument-in-route-templates
πŸ‘— no-multiple-empty-lines
βœ… no-negated-condition
βœ… no-nested-interactive
no-nested-landmark
no-nested-splattributes
βœ… no-obsolete-elements
βœ… no-outlet-outside-routes
βœ… no-partial
no-passed-in-event-handlers
πŸ”§ no-positional-data-test-selectors
βœ… no-positive-tabindex
no-potential-path-strings
βœ… no-quoteless-attributes
πŸ”§ no-redundant-fn
no-redundant-landmark-role
no-restricted-invocations
βœ… no-shadowed-elements
πŸ‘— no-trailing-spaces
βœ… no-triple-curlies
no-unbalanced-curlies
βœ… no-unbound
βœ… no-unnecessary-component-helper
πŸ‘— no-unnecessary-concat
βœ… no-unused-block-params
no-whitespace-for-layout
no-whitespace-within-word
no-yield-only
πŸ‘— quotes
βœ…πŸ”§ require-button-type
require-each-key
require-form-method
βœ… require-iframe-title
require-input-label
require-lang-attribute
βœ… require-valid-alt-text
πŸ‘— self-closing-void-elements
βœ… simple-unless
splat-attributes-only
βœ… style-concatenation
βœ… table-groups
template-length

Severity Levels

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" ] }
}

Per Template File

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

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

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

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

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

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

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

and to configure rules in the template:

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

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

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

{{!-- template-lint-configure no-bare-strings "warn"  --}}

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.

Defining your own rules

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

Supporting the --fix option

You can add a fixer to a rule. See fixer documentation for more details.

Sharing configs

It is possible to share a config (extends) or plugin (custom rules) across projects. See ember-template-lint-plugin-peopleconnect for an example.

Semantic Versioning Policy

The semver policy for this addon can be read here: semver policy.

Contributing

See the Contributing Guidelines for information on how to help out.

License

This project is licensed under the MIT License.

About

Linter for Ember or Handlebars templates

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 100.0%