{"id":23769714,"url":"https://github.com/ni/javascript-styleguide","last_synced_at":"2025-09-05T14:32:47.555Z","repository":{"id":38994199,"uuid":"286836621","full_name":"ni/javascript-styleguide","owner":"ni","description":"JavaScript and TypeScript Style Guide","archived":false,"fork":false,"pushed_at":"2024-10-18T22:00:57.000Z","size":956,"stargazers_count":9,"open_issues_count":23,"forks_count":9,"subscribers_count":40,"default_branch":"main","last_synced_at":"2024-12-24T22:38:46.511Z","etag":null,"topics":["eslint","javascript","typescript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ni.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-11T19:59:50.000Z","updated_at":"2024-10-18T22:01:02.000Z","dependencies_parsed_at":"2023-02-15T10:46:25.023Z","dependency_job_id":"aada8650-9edf-4c2d-8c20-f35d90268d32","html_url":"https://github.com/ni/javascript-styleguide","commit_stats":{"total_commits":124,"total_committers":8,"mean_commits":15.5,"dds":"0.42741935483870963","last_synced_commit":"8e11a5f7fa9b7af94e5d19989e4fed2f37b4a881"},"previous_names":[],"tags_count":78,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ni%2Fjavascript-styleguide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ni%2Fjavascript-styleguide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ni%2Fjavascript-styleguide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ni%2Fjavascript-styleguide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ni","download_url":"https://codeload.github.com/ni/javascript-styleguide/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232044694,"owners_count":18464623,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eslint","javascript","typescript"],"created_at":"2025-01-01T02:31:52.800Z","updated_at":"2025-01-01T02:31:56.762Z","avatar_url":"https://github.com/ni.png","language":"JavaScript","funding_links":[],"categories":["Development Utilities"],"sub_categories":["Linting"],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003cdiv\u003e\n        \u003c!-- Load images from raw.githubusercontent.com to enable image rendering when viewed from npmjs.com --\u003e\n        \u003cimg src=\"https://raw.githubusercontent.com/ni/javascript-styleguide/HEAD/docs/logo.svg\" alt=\"JavaScript, TypeScript, and NI logo\" width=\"300\" height=\"100\"\u003e\n    \u003c/div\u003e\n\u003c/div\u003e\n\n# NI JavaScript and TypeScript Style Guide\n\n[![NPM Version](https://img.shields.io/npm/v/@ni/eslint-config-javascript.svg?label=@ni/eslint-config-javascript)](https://www.npmjs.com/package/@ni/eslint-config-javascript)\n[![NPM Version](https://img.shields.io/npm/v/@ni/eslint-config-typescript.svg?label=@ni/eslint-config-typescript)](https://www.npmjs.com/package/@ni/eslint-config-typescript)\n[![NPM Version](https://img.shields.io/npm/v/@ni/eslint-config-angular.svg?label=@ni/eslint-config-angular)](https://www.npmjs.com/package/@ni/eslint-config-angular)\n[![NPM Version](https://img.shields.io/npm/v/@ni/eslint-config-playwright.svg?label=@ni/eslint-config-playwright)](https://www.npmjs.com/package/@ni/eslint-config-playwright)\n\nWelcome to NI's JavaScript and TypeScript linter rules for [ESLint](https://eslint.org/docs/user-guide/getting-started).\n\n## Installation\n\nInstall the package for your corresponding language as a development dependency:\n\n- For JavaScript run:\n\n    ```bash\n    npm install -D @ni/eslint-config-javascript\n    ```\n\n   Then follow the [JavaScript configuration](#javascript-configuration) instructions.\n- For TypeScript run:\n\n    ```bash\n    npm install -D @ni/eslint-config-typescript\n    ```\n\n    Then follow the [TypeScript configuration](#typescript-configuration) instructions.\n- For Angular run:\n\n    ```bash\n    npm install -D @ni/eslint-config-angular\n    ```\n\n    Then follow the [Angular configuration](#angular-configuration) instructions.\n- For Playwright run:\n\n    ```bash\n    npm install -D @ni/eslint-config-playwright\n    ```\n\n    Then follow the [Playwright configuration](#playwright-configuration) instructions.\n\nWith npm 7 and up the required peer dependencies will be installed automatically and you can move on to [Configuration](#configuration).\n\nIf you are using npm 6 or lower, use the following instructions to manually install the required peer dependencies:\n\nUse [`npm view`](https://docs.npmjs.com/cli/view.html) to list the correct versions of each peer package to install yourself. For example, with a JavaScript project run:\n\n```bash\nnpm view @ni/eslint-config-javascript peerDependencies\n```\n\nAlternatively, use [`npx install-peerdeps`](https://www.npmjs.com/package/install-peerdeps) as a shortcut to install the peer packages for you. For example, with a JavaScript project run:\n\n```bash\nnpx install-peerdeps --dev @ni/eslint-config-javascript\n```\n\n## Configuration\n\nAfter installing the lint configuration packages, follow the configuration instructions for your project language:\n\n### JavaScript configuration\n\nExtend `@ni/eslint-config-javascript` in the [ESLint configuration](https://eslint.org/docs/user-guide/configuring/configuration-files#configuration-file-formats).\n\n```js\n{\n    extends: '@ni/eslint-config-javascript'\n}\n```\n\n### TypeScript configuration\n\nExtend `@ni/eslint-config-typescript` and `@ni/eslint-config-typescript/requiring-type-checking` in the [ESLint configuration](https://eslint.org/docs/user-guide/configuring/configuration-files#configuration-file-formats). Set the `parserOptions.project` configuration to the project's TypeScript configuration.\n\n```js\n{\n    extends: [\n        '@ni/eslint-config-typescript',\n        '@ni/eslint-config-typescript/requiring-type-checking'\n    ],\n    parserOptions: {\n        project: 'tsconfig.json'\n    }\n}\n```\n\n### Angular configuration\n\nESLint support for Angular is provided by [`@angular-eslint`](https://github.com/angular-eslint/angular-eslint#readme). **It's recommended to use `@angular-eslint/schematics` to\nconfigure ESLint for Angular projects**.\n\n1. **For single and multi-project workspaces**, [add the schematic](https://github.com/angular-eslint/angular-eslint#quick-start). Remove the `@angular-eslint`, `@typescript-eslint`, and `eslint` dependencies from `package.json`.\n    ```bash\n    ng add @angular-eslint/schematics\n    ```\n2. **For multi-project workspaces**, [configure each project](https://github.com/angular-eslint/angular-eslint#adding-eslint-configuration-to-an-existing-angular-cli-project-which-has-no-existing-linter), and then enable future generated projects to be configured as well.\n    ```bash\n    \u003e ng g @angular-eslint/schematics:add-eslint-to-project \u003cPROJECT NAME\u003e\n    \u003e ng config cli.schematicCollections \"[\\\"@angular-eslint/schematics\\\"]\"\n    ```\n3. Extend the NI configured rules for Angular and Angular templates in the [ESLint configuration](https://eslint.org/docs/user-guide/configuring/configuration-files#configuration-file-formats). Set the `parserOptions.project` configuration to the project's TypeScript configuration.\n    ```js\n    overrides: [{\n        files: ['*.ts'],\n        extends: [\n            '@ni/eslint-config-angular',\n            '@ni/eslint-config-angular/requiring-type-checking'\n        ],\n        parserOptions: {\n            project: 'tsconfig.json'\n        }\n    }, {\n        files: ['*.html'],\n        extends: ['@ni/eslint-config-angular/template']\n    }]\n    ```\n4. Evaluate the [project specific rule groups](#evaluate-project-specific-rule-groups) to manually add to your lint configuration. For Angular applications in particular, consider enabling the [`[application-prefix]`](#application-prefix) rule group.\n\n### Playwright configuration\n\nExtend `@ni/eslint-config-playwright` and `@ni/eslint-config-playwright/requiring-type-checking` in the [ESLint configuration](https://eslint.org/docs/user-guide/configuring/configuration-files#configuration-file-formats). Set the `parserOptions.project` configuration to the project's TypeScript configuration.\n\n**Note:** The Playwright configurations extend the TypeScript configurations, so it is not necessary for an application to extend them both. However, the Playwright configurations should only be applied to directories that contain Playwright tests and utilities.\n\n```js\n// This is an example .eslintrc.js in a Playwright-specific directory.\n// If Playwright files are mixed with other code, use an \"overrides\" file pattern to match only Playwright code.\n{\n    extends: [\n        '@ni/eslint-config-playwright',\n        '@ni/eslint-config-playwright/requiring-type-checking'\n    ],\n    parserOptions: {\n        project: 'tsconfig.json'\n    }\n}\n```\n\n## Usage\n\nAfter following the above steps to install and configure the linter, you should be able to run it from the command line using `npx eslint .`\n\n### Scripts\n\nTo avoid developers needing to remember tooling-specific commands, each project should add standard aliases to its `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"lint\": \"eslint .\",\n    \"lint:fix\": \"eslint . --fix\",\n  }\n}\n```\n\nThis allows developers to lint using `npm run lint` and to run the automatic fixer using `npm run lint:fix`.\n\n### Add linting to your PR build\n\nEach 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 after installing dependencies and building your application (not shown in the examples).\n\n### GitHub Actions\n\n[Ensure npm is present on the agent](https://github.com/actions/setup-node/) then run the lint command.\n\n```yml\njobs:\n  build:\n    steps:\n      - uses: actions/setup-node@v1\n        with:\n          node-version: '16'\n      - run: npm run lint\n```\n\n### Azure Pipelines\n\nUse the [npm task](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/package/npm?view=azure-devops) to run the lint command.\n\n```yml\n  - task: Npm@1\n    displayName: 'Lint'\n    inputs:\n      command: custom\n      customCommand: 'run lint'\n```\n\n## Tips for Adopting this Style Guide\n\n### Enable as early as possible\n\n**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.\n\n**Existing projects** are likely to have numerous violations even if they already used a different linter (for example, the deprecated [TSLint](https://www.npmjs.com/package/tslint)) as this ruleset is more strict than most. The recommended flow for adopting this ruleset in an existing repository is:\n1. Install the tooling as described above.\n2. Disable existing lint tooling.\n3. Fix as many simple violations as possible by running the automated fixer and doing targeted manual fixes.\n4. If necessary, suppress the remaining violations but fix them as soon as possible in follow up submissions.\n\nTypically 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.\n\n### Evaluate project-specific rule groups\n\nSeveral 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.\n\nText 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.\n\n#### Application prefix\n\nTag: [`[application-prefix]`](https://github.com/ni/javascript-styleguide/search?q=%5Bapplication-prefix%5D\u0026type=code)\n\nPrefixes 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.\n\n#### Strict null checks\n\nTag: [`[strict-null-checks]`](https://github.com/ni/javascript-styleguide/search?q=%5Bstrict-null-checks%5D\u0026type=code)\n\nWhen `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;`.\n\n`strictNullChecks` are a powerful tool for code correctness and give us a way to avoid [\"The Billion Dollar Mistake\"](https://www.infoq.com/presentations/Null-References-The-Billion-Dollar-Mistake-Tony-Hoare/). 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.\n\nAs such, `strictNullChecks` are not recommended by default in order to prevent overhead of rule adoption for existing applications.\n\nHowever, 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.\n\n#### Accessibility\n\nTag: [`[accessibility]`](https://github.com/ni/javascript-styleguide/search?q=%5Baccessibility%5D\u0026type=code)\n\nThere currently isn't an NI organization wide requirement to enforce accessibility in applications. The rule group should be enabled if individual applications prioritize accessibility.\n\n### Globally disable rules that don't apply to a codebase or directory\n\nA 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:\n1. As a temporary measure to stage adoption of the tooling.\n2. As a permanent measure if the rule is incompatible with a project's configuration. The rule configuration files in each package (`packages/eslint-config-*/index.js`) contain comments on each rule if it might commonly be disabled. Some examples include:\n   - consider disabling `@angular-eslint/template/i18n` if a project will never be localized\n   - consider disabling `func-names` in older JavaScript projects that make use of immediately-invoked function expressions (IIFEs) where providing a name is not useful\n3. As a permanent measure for an existing codebase if the Technical Lead determines it is too costly to fix the violations of that rule.\n\nEach disabled rule (or group of similar rules) should include a comment explaining why it is disabled.\n\nTo disable a rule globally, modify the `rules` section of the [ESLint configuration](https://eslint.org/docs/user-guide/configuring/configuration-files#configuration-file-formats):\n```js\n    rules: {\n        // This rule is disabled as an example\n        'import/prefer-default-export': 'off'\n    }\n```\n\nTo disable a rule for a specific file pattern or directory, modify the `overrides` section of the [ESLint configuration](https://eslint.org/docs/user-guide/configuring/configuration-files#configuration-file-formats):\n```js\n    overrides: [{\n        files: ['*.stories.ts'],\n        rules: {\n            // This rule is disabled as an example\n            'import/no-default-export': 'off'\n        }\n    }]\n```\n\n### Inline disable rules that don't apply to a particular situation\n\nA 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.\n\nThe rule configuration files in this package (`index.js`, `typescript.js`, etc) contain comments on each rule if it might commonly be disabled.\n\nESLint offers several [ways to disable a rule for a line or file](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules). Suppressions should be as targeted as possible and should include a comment explaining the suppression.\n\n### Recommended Development Environment Configuration\n\nModern IDEs can be configured to provide live feedback about ESLint errors.\n\n#### Visual Studio Code\n\nInstall the [ESLint Extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint).\n\n\u003c!-- Load images from raw.githubusercontent.com to enable image rendering when viewed from npmjs.com --\u003e\n![VSCode Extension](https://raw.githubusercontent.com/ni/javascript-styleguide/HEAD/docs/VSCodeESLintExtension.png)\n\nYou can [configure a repository to prompt developers to install this extension](https://code.visualstudio.com/docs/editor/extension-marketplace#_workspace-recommended-extensions) by adding a file called `.vscode/extensions.json` with the following contents:\n\n```json\n{\n    \"recommendations\": [\n        \"dbaeumer.vscode-eslint\",\n    ]\n}\n```\n\nFollow the `@angular-eslint` [instructions](https://github.com/angular-eslint/angular-eslint#linting-html-files-and-inline-templates-with-the-vscode-extension-for-eslint) for linting HTML files and inline-templates with Angular.\n\n#### JetBrains WebStorm\n\nFollow the [instructions in the WebStorm documentation](https://www.jetbrains.com/help/webstorm/eslint.html#ws_js_eslint_activate) to activate and configure ESLint automatically in the Settings ≫ Preferences dialog.\n\n## Troubleshooting\n\n### JavaScript Heap Out of Memory\n\nIncrease the heap allocation using the `max_old_space_size` option.\n```bash\nnode --max_old_space_size=8196 ./node_modules/eslint/bin/eslint\n```\n\nThis option can be adapted for npm scripts, for example.\n```json\n\"ng\": \"node --max_old_space_size=8196 ./node_modules/@angular/cli/bin/ng\",\n\"lint\": \"npm run ng -- lint\"\n```\n\n## Performance\n\n### TypeScript linting performance\n\n`@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.\n\nIf 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.\n\nSee discussion in the [performance section](https://github.com/typescript-eslint/typescript-eslint/blob/main/docs/getting-started/linting/TYPED_LINTING.md#performance) of the Getting Started - Linting with Type Information guide.\n\n### Angular linting performance\n\nDeviations from the `@angular-eslint schematic`, `@ni/eslint-config-angular`, and the [`parserOptions.project`](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser#parseroptionsproject) configurations can result in significant performance degredation. Fully manual configuration [is not recommended](https://github.com/angular-eslint/angular-eslint#going-fully-manual-not-recommended). Read `@angular-eslint`'s [section on performance](https://github.com/angular-eslint/angular-eslint#eslint-configs-and-performance) for information on addressing slow linting processes.\n\n## License\n\n[MIT (c) 2021 National Instruments Corporation](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fni%2Fjavascript-styleguide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fni%2Fjavascript-styleguide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fni%2Fjavascript-styleguide/lists"}