This package has been deprecated

    Author message:

    The package @ni/eslint-config is deprecated. Please use one of @ni/eslint-config-javascript, @ni/eslint-config-typescript, or @ni/eslint-config-angular instead. See https://www.github.com/ni/javascript-styleguide for more information.

    @ni/eslint-config

    2.0.1 • Public • Published
    JavaScript, TypeScript, and NI logo

    NI JavaScript and TypeScript Style Guide

    NPM Version

    Welcome to NI's JavaScript and TypeScript linter rules for ESLint.

    Installation

    Install @ni/eslint-config and its peer dependencies.

    Use npm view to list the correct versions of each package to install yourself.

    npm view @ni/eslint-config peerDependencies

    Alternatively, use npx install-peerdeps as a shortcut to install the packages for you.

    npx install-peerdeps --dev @ni/eslint-config

    Angular Installation

    Follow the instructions below to use a schematic to install dependencies.

    Configuration

    JavaScript

    Extend @ni in the ESLint configuration.

    {
        extends: '@ni'
    }

    TypeScript

    Extend @ni/eslint-config/typescript and @ni/eslint-config/typescript-requiring-type-checking in the ESLint configuration. Set the parserOptions.project configuration to the project's TypeScript configuration.

    {
        extends: [
            '@ni/eslint-config/typescript',
            '@ni/eslint-config/typescript-requiring-type-checking'
        ],
        parserOptions: {
            project: 'tsconfig.json'
        }
    }

    Angular

    ESLint support for Angular is provided by @angular-eslint. It's recommended to use @angular-eslint/schematics to configure ESLint for Angular projects especially when migrating from TSLint. Use version 1.x.x for Angular versions less than 11.2.0.

    1. Use the schematic to add ESLint to new workspaces version 12+, and new applications and libraries will be generated with ESLint as well.
      > ng add @angular-eslint/schematics
    2. Extend @ni/eslint-config/angular and @ni/eslint-config/typescript-requiring-type-checking in the ESLint configuration for TypeScript and @ni/eslint-config/angular-template for templates.
      overrides: [{
          files: ['*.ts'],
          // ...
          extends: [
              '@ni/eslint-config/angular',
              '@ni/eslint-config/typescript-requiring-type-checking'
          ]
      }, {
          files: ['*.html']
          // ...
          extends: ['@ni/eslint-config/angular-template'],
      }]
    3. For existing workspaces, migrate each project. When all projects have been migrated, new applications and libraries will be generated with ESLint as well. Enter yes for both options to remove TSLint and ignore its configuration.
      ng g @angular-eslint/schematics:convert-tslint-to-eslint <PROJECT NAME>
    4. Evaluate the project specific rule groups to manually add to your lint configuration. For Angular applications in particular, consider enabling the [application-prefix] rule group.

    Usage

    After following the above steps to install and configure the linter, you should be able to run it from the command line using npx eslint .

    NPM commands

    To avoid developers needing to remember tooling-specific commands, each project should add standard aliases to its package.json:

    {
      "scripts": {
        "lint": "eslint .",
        "lint-fix": "eslint . --fix",
      }
    }

    This allows developers to lint using npm run lint and to run the automatic fixer using npm run lint-fix.

    Add linting to your PR build

    Each project's pull request build pipeline should ensure no lint errors can be committed to the repository. Invoke npm run lint from your GitHub Actions or Azure Pipelines YML.

    Tips for Adopting this Style Guide

    Enable as early as possible

    New projects should turn on linting before writing any code. It's easier to fix violations as developers add new code than it is to fix large numbers of lint errors across an existing codebase.

    Existing projects are likely to have numerous violations even if they already used a different linter (for example, the deprecated TSLint) as this ruleset is more strict than most. The recommended flow for adopting this ruleset in an existing repository is:

    1. Install the tooling as described above.
    2. Disable existing lint tooling.
    3. Fix as many simple violations as possible by running the automated fixer and doing targeted manual fixes.
    4. If necessary, suppress the remaining violations but fix them as soon as possible in follow up submissions.

    Typically steps 1-3 will happen in a single pull request (or a few in quick succession) while step 4 will be split across many subsequent submissions as time permits.

    Evaluate project-specific rule groups

    Several sets of rules may be enabled based on requirements of a given project. By default the following sets of rules are in an inert / disabled state, but should be evaluated for your integration.

    Text search for the tag associated with a specific rule group in the repository to find the related rules. If enabling a rule group, the rules should be toggled from 'off' to 'error' unless the rule comment says otherwise.

    Application prefix

    Tag: [application-prefix]

    Prefixes are generally added to named objects such as the selector for Components in Angular applications. Projects should consider enabling this rule group so that names can be consistently prefixed making them easier to share between applications and to minimize the chance of conflicts when using shared libraries.

    Strict null checks

    Tag: [strict-null-checks]

    When strictNullChecks are enabled the values null and undefined are treated as distinct types by the compiler. For example, with strictNullChecks enabled, the value null could not be directly assigned to a binding of a Cat object, ie const cat: Cat = null would be a compile error. The null value is a distinct type and the binding would have to explicitly state that it can have a null value, ie const cat: Cat | null = null;.

    strictNullChecks are a powerful tool for code correctness and give us a way to avoid "The Billion Dollar Mistake". However, it can be impractical to retrofit strictNullChecks configuration into an existing application and requires expanding your mental model for software development for use in new applications.

    As such, strictNullChecks are not recommended by default in order to prevent overhead of rule adoption for existing applications.

    However, we encourage new applications to leverage strictNullChecks for development. Enabling strictNullChecks is the TypeScript compiler recommendation and it is enabled by default in new Angular applications.

    Accessibility

    Tag: [accessibility]

    There currently isn't an NI organization wide requirement to enforce accessibility in applications. The rule group should be enabled if individual applications prioritize accessibility.

    Globally disable rules that don't apply to a codebase or directory

    A project should strive to adopt this configuration as fully as possible, but there are valid reasons to disable a rule across a codebase or specific directory:

    1. As a temporary measure to stage adoption of the tooling.
    2. As a permanent measure if the rule is incompatible with a project's configuration. The rule configuration files in this package (index.js, typescript.js, etc) contain comments on each rule if it might commonly be disabled. Some examples include:
      • consider disabling @typescript-eslint/no-floating-promises in test code for Angular projects because it is incompatible with the jasminewd2 library
      • consider disabling func-names in older JavaScript projects that make use of immediately-invoked function expressions (IIFEs) where providing a name is not useful
    3. As a permanent measure for an existing codebase if the Technical Lead determines it is too costly to fix the violations of that rule.

    Each disabled rule (or group of similar rules) should include a comment explaining why it is disabled.

    To disable a rule globally, modify the rules section of the ESLint configuration:

        rules: {
            // This rule is disabled as an example
            'import/prefer-default-export': 'off'
        }

    To disable a rule for a specific file pattern or directory, modify the overrides section of the ESLint configuration:

        overrides: [{
            files: ['*.stories.ts'],
            rules: {
                // This rule is disabled as an example
                'import/no-default-export': 'off'
            }
        }]

    Inline disable rules that don't apply to a particular situation

    A project should strive to adopt this configuration as fully as possible, but there are valid reasons to disable a rule (also called suppressing a violation) for a specific line, block, or file of code.

    The rule configuration files in this package (index.js, typescript.js, etc) contain comments on each rule if it might commonly be disabled.

    ESLint offers several ways to disable a rule for a line or file. Suppressions should be as targeted as possible and should include a comment explaining the suppression.

    Recommended Development Environment Configuration

    Modern IDEs can be configured to provide live feedback about ESLint errors.

    Visual Studio Code

    Install the ESLint Extension.

    VSCode Extension

    You can configure a repository to prompt developers to install this extension by adding a file called .vscode/extensions.json with the following contents:

    {
        "recommendations": [
            "dbaeumer.vscode-eslint",
        ]
    }

    Follow the @angular-eslint instructions for linting HTML files and inline-templates with Angular.

    JetBrains WebStorm

    Follow the instructions in the WebStorm documentation to activate and configure ESLint automatically in the Settings ≫ Preferences dialog.

    Troubleshooting

    JavaScript Heap Out of Memory

    Increase the heap allocation using the max_old_space_size option.

    node --max_old_space_size=8196 ./node_modules/eslint/bin/eslint

    This option can be adapted for npm scripts, for example.

    "ng": "node --max_old_space_size=8196 ./node_modules/@angular/cli/bin/ng",
    "lint": "npm run ng -- lint"

    Performance

    TypeScript linting performance

    @ni/eslint-config/typescript-requiring-type-checking includes rules that require type checking that run slower as they utilize the TypeScript compiler for type information.

    If there are situations where the analysis time for enabling the type checked rules is an excessive burden you may consider creating a separate ESLint configuration that avoids extending the type checked rules and omits the parserOptions.project configuration to run in specific scenarios.

    See discussion in the performance section of the Getting Started - Linting with Type Information guide.

    Angular linting performance

    Deviations from the @angular-eslint schematic, @ni/eslint-config, and the parserOptions.project configurations can result in significant performance degredation. Fully manual configuration is not recommended. Read @angular-eslint's section on performance for information on addressing slow linting processes.

    License

    MIT (c) 2021 National Instruments Corporation

    Install

    npm i @ni/eslint-config

    DownloadsWeekly Downloads

    54

    Version

    2.0.1

    License

    MIT

    Unpacked Size

    62 kB

    Total Files

    11

    Last publish

    Collaborators

    • ni-webapps-ops