Skip to content

docs: add global variable rule disabling FAQ for ESLint #9865

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Aug 28, 2024
Merged

docs: add global variable rule disabling FAQ for ESLint #9865

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9df9fee
docs: add global variable rule disabling FAQ for ESLint
JoshuaKGoldberg Aug 22, 2024
071c1b2
Linked to FAQ too, good idea
JoshuaKGoldberg Aug 25, 2024
69dc455
disable-next-line
JoshuaKGoldberg Aug 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions docs/troubleshooting/faqs/ESLint.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,51 @@ module.exports = {

If you choose to leave on the ESLint `no-undef` lint rule, you can [manually define the set of allowed `globals` in your ESLint config](https://eslint.org/docs/user-guide/configuring/language-options#specifying-globals), and/or you can use one of the [pre-defined environment (`env`) configurations](https://eslint.org/docs/user-guide/configuring/language-options#specifying-environments).

## I get errors from the `@typescript-eslint/no-namespace` and/or `no-var` rules about declaring global variables

Two common solutions in TypeScript for declaring the existence of a global variable include:

- `declare global` with a `var`, which violates [`no-var`](https://eslint.org/docs/latest/rules/no-var):

```ts
declare global {
var myValue: string;
// Unexpected var, use let or const instead. eslint (no-var)
}

myValue;
```

- `declare namespace globalThis`, which violates [`@typescript-eslint/no-namespace`](https://typescript-eslint.io/rules/no-namespace):

```ts
declare namespace globalThis {
// ES2015 module syntax is preferred over namespaces. eslint (@typescript-eslint/no-namespace)
let myValue: string;
}

globalThis.myValue;
```

[Using global variables is generally discouraged](https://stackoverflow.com/questions/10525582/why-are-global-variables-considered-bad-practice).
If possible, it's best to avoid declaring globals altogether.

If you absolutely must use one of the two strategies, then you can use an [ESLint configuration comment](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) to disable rules as needed.
For example:

```ts
declare global {
// eslint-disable-next-line no-var -- Provided by an old third-party integration.
var myValue: string;
}
```

:::tip
Whenever you need to disable an ESLint rule, it's best to include an informative comment explaining why.
:::

See [#9582](https://github.com/typescript-eslint/typescript-eslint/issues/9582 'typescript-eslint/typescript-eslint#9582 Docs: globalThis without ignores of no-var and no-namespace') and [#7941](https://github.com/typescript-eslint/typescript-eslint/issues/7941 'typescript-eslint/typescript-eslint#7941 Base rule extension: no-var configuration for declarations') for discussions around typescript-eslint supporting these use cases.

## Can I use ESLint's `--cache` with typescript-eslint?

[ESLint's `--cache` option](https://eslint.org/docs/latest/use/command-line-interface#caching) caches on a per-file basis.
Expand Down
3 changes: 3 additions & 0 deletions packages/eslint-plugin/docs/rules/no-namespace.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,9 @@ You might consider using [ESLint disable comments](https://eslint.org/docs/lates

## Further Reading

{/* cspell:disable-next-line */}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI I think you can configure cspell to ignore anchors using ignore patterns

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh?? OH?? That would be so nice...

I can't find anything Googling, but if you have a reference I would very very happily send a PR to enable it & remove any now-unnecessary disables/ignores.


- [FAQ: I get errors from the `@typescript-eslint/no-namespace` and/or `no-var` rules about declaring global variables](/troubleshooting/faqs/eslint#i-get-errors-from-the-typescript-eslintno-namespace-andor-no-var-rules-about-declaring-global-variables)
- [Modules](https://www.typescriptlang.org/docs/handbook/modules.html)
- [Namespaces](https://www.typescriptlang.org/docs/handbook/namespaces.html)
- [Namespaces and Modules](https://www.typescriptlang.org/docs/handbook/namespaces-and-modules.html)
Loading