Have ideas to improve npm?Join in the discussion! »

    isml-linter

    5.35.1 • Public • Published

    ISML Linter

    ISML Linter is a tool for examining if your project's templates follow a specified set of rules defined by your dev team. The available rules can be roughly grouped into:

    • Styles that are defined by your team;
    • Syntactic errors related to <is* > tags;
    • Coding conventions recommended by SalesForce;
    • Git conflicts that may accidentally be left unresolved;

    Please feel free to make suggestions and help make this linter better. :) The set of currently available rules can be found below.

    ISML Linter is also available as a VSCode extension, give it a try!

    Installation

    Prerequisite: Node.js (>=10.0.0).

    Simply run in your project's root directory:

    $ npm install isml-linter --save-dev

    and add the following to package.json:

    "scripts": {
        "init:isml":  "./node_modules/.bin/isml-linter --init",
        "lint:isml":  "./node_modules/.bin/isml-linter",
        "build:isml": "./node_modules/.bin/isml-linter --build",
        "fix:isml":   "./node_modules/.bin/isml-linter --autofix"
    }

    Here's what each script does:

    • init:isml creates a config file;
    • lint:isml simply lists the broken rules in the console;
    • build:isml raises an error if there is any broken rule, thus can be used in your build process;
    • fix:isml applies fixes for the enabled rules;

    Configuration

    After adding the above scripts to package.json, run the following command to generate a config file containing all available rules:

    npm run init:isml
    

    Alternatively, you can manually create a configuration file, make sure it is in the project root directory and has one of the following names: ismllinter.config.js, .ismllintrc.js or .ismllinter.json.

    You can disable any rule by removing it from the config file. You may also find these configuration options useful:

    Config Description
    rootDir The root directory under which the linter will run. Defaults to the directory where the package.json file is
    disableHtml5 Disallows HTML5-defined unclosed tags, such as input, img and meta. Default: false
    ignoreUnparseable Does not raise an error if an unparseable template is found. Default: false. Please check "Parse Modes - Tree" section below
    ignore If a template path contains (as a substring) any string defined here, that template will be ignored by the linter
    indent [Deprecated] Please check indent docs. Indentation size. Default: 4
    linebreakStyle unix or windows. Default: unix
    eslintConfig Path to a eslint configuration file, to be applied within <isscript> tags. Default: .eslintrc.json
    enableCache [Deprecated] Please check cache docs. Default: false
    autoFix Applies fixes for enabled rules. Default: false
    printPartialResults Prints partial results. Useful to get overall picture in case of many errors. Default: false
    disableTreeParse Enables only rules that do not depend on building an ISML tree. Check below when this might be useful. Default: false
    rules Defines which rules to check. See available rules below

    Note: If you explicitly set "ignoreUnparseable" config to true, unparseable templates may contain errors that will not be detected by ISML Linter.

    Example configuration:

    {
        "rootDir": "./cartridges",
        "ignore": [
            "this_directory_is_to_be_ignored"
            "Email.isml"
        ],
        "rules" : {
            "no-br" : {}, 
            "enforce-require" : {}
        }
    }

    Note that according to the above configurations, the following templates would be ignored by ISML Linter:

    • registerEmail.isml
    • some/path/welcomeEmail.isml
    • this_directory_is_to_be_ignored/producttile.isml
    • some/path/this_directory_is_to_be_ignored/confirmationpage.isml

    Parse Modes

    Tree (disableTreeParse : false)

    This is the default, and most powerful mode. It analyses the template and tries to build an "ISML-DOM" tree to then apply the enabled rules. It is required that the template is parseable.

    For example, if a template contains a snippet like the following, IT IS NOT considered a parseable template:

    <isif condition="${aCondition}">
        <div class="info">
    </isif>
            Some content
    <isif condition="${aCondition}">
        </div>
    </isif>

    since the linter is not able to make an association between the opening and the corresponding closing <div> elements. This is the only known limitation for this parse mode. One possible solution to turn such templates into parseable is to replace that snippet by:

    <isif condition="${aCondition}">
        <div class="info">
            <isinclude template="myTemplate" />
        </div>
    <iselse/>
        <isinclude template="myTemplate" />
    </isif>

    There are other possible, potentially more "best-practice" approaches, but it goes beyond the scope of this article.

    And, to avoid possible doubts, here is an extra piece of information: it is allowed to have isml tags within html tags, such as:

    <div <isif ...> </isif> />

    Line by Line (disableTreeParse : true)

    This is a more robust, less powerful mode. It only has a few set of rules available and is indicated for cases where there are many, many lint errors and you want fix them gradually. It is also recommended in cases you don't want to force templates to be parseable (see previous section). This mode is ideally temporary, as it cannot take advantages of even some simple rules, such as indentation checking.

    Command Line Interface

    Please check CLI docs.

    Git Hooks (Optional)

    To prevent new errors to be introduced in next pushes, we recommend using some git hook npm package, such as husky or ghooks. The following example works for ghook:

    "config": {
        "ghooks": {
          "pre-push": "npm run build:isml"
        }
    }

    API

    Check the API docs.

    Available Rules

    Rule Description
    no-br Disallows <br/> tags. Enable this rule if you prefer to use CSS to handle vertical spacing
    no-git-conflict Disallows unresolved Git conflicts
    no-import-package Disallows importPackage() function. It is recommended by SalesForce to use require() instead
    no-isscript Disallows <isscript/> tag in template. Enable this rule if you prefer logic to be kept in a separate .ds/.js file
    🔧 no-trailing-spaces Disallows trailing blank spaces
    🔧 no-space-only-lines Disallows lines that contain only blank spaces, i.e., unnecessarily indented
    no-inline-style Disallows use of "style" HTML attribute. Enable this rule if you prefer style to be fully handled via CSS
    🔧 no-tabs Disallows use of tabs
    enforce-isprint [KNOWN BUG] Enforces every ${string} to be wrapped by an <isprint/> tag
    enforce-require Disallows direct calls to a DigitalScript class, such as in:
    var PaymentMgr = dw.order.PaymentMgr;
    For this case, it is recommended to use instead:
    var PaymentMgr = require('dw/order/PaymentMgr');
    lowercase-filename Disallows template names to have uppercase characters
    max-lines Limits the size of templates
    🔸 no-hardcode Disallows hardcoded strings outside ISML expressions
    🔧 🔸 indent Sets indentation size
    🔸 no-require-in-loop No require() calls from within a loop in the template
    🔸 no-embedded-isml Disallows embedded isml tags, such as in <div <isif /> />, except for <isprint />
    🔸 max-depth Sets the maximum of nested elements in a template
    🔸 disallow-tags Disallows tags specified at rule level
    🔸 one-element-per-line One element per line
    🔧 🔸 leading-iscontent Ensures <iscontent> tag is the first element in the template if present
    🔧 🔸 leading-iscache Ensures <iscache> tag is among the first element in the template if present
    🔸 no-deprecated-attrs Disallows deprecated attributes or attribute values
    🔸 contextual-attrs Disallows presence of mutually exclusive attributes
    🔸 custom-tags Checks if "util/modules" template is actually needed or if it is missing
    🔧 🔸 eslint-to-isscript Applies ESLint rules to <isscript> tag content
    🔧 🔸 no-iselse-slash Disallows self-closing <iselse> and <iselseif> tags
    🔸 empty-eof Enforces a empty line at the end of the template
    🔸 align-isset Aligns contiguous <isset> tags attributes' columns
    💥 🔸 enforce-security Enforces security measures

    You are more than welcome to contribute with us! Please check the contribute section.

    Donations

    This project was conceived by its author without any financial support, with the intention to help the community improving and speeding up any projects that involve ISML templates. If you think ISML Linter has helped you and your team, please consider making a donation, it will be much appreciated!

    Iconography

    Deprecated feature
    💥 New feature
    🔸 Rules that require "disableTreeParse" configuration not to be true.
    🔧 Auto-fix available

    Install

    npm i isml-linter

    DownloadsWeekly Downloads

    3,776

    Version

    5.35.1

    License

    MIT

    Unpacked Size

    215 kB

    Total Files

    61

    Last publish

    Collaborators

    • avatar