diff --git a/.cspell.json b/.cspell.json index ceccb1328b77..811ef9e62dd7 100644 --- a/.cspell.json +++ b/.cspell.json @@ -95,6 +95,7 @@ "nocheck", "noninteractive", "nullish", + "onboarded", "OOM", "OOMs", "parameterised", diff --git a/packages/eslint-plugin/docs/rules/no-explicit-any.md b/packages/eslint-plugin/docs/rules/no-explicit-any.md index 268089404a4a..5694ebf709a1 100644 --- a/packages/eslint-plugin/docs/rules/no-explicit-any.md +++ b/packages/eslint-plugin/docs/rules/no-explicit-any.md @@ -127,8 +127,16 @@ interface Garply { ## When Not To Use It -If an unknown type or a library without typings is used -and you want to be able to specify `any`. +`any` is always a dangerous escape hatch. +Whenever possible, it is always safer to avoid it. +TypeScript's `unknown` is almost always preferable to `any`. + +However, there are occasional situations where it can be necessary to use `any`. +Most commonly: + +- If your project isn't fully onboarded to TypeScript yet, `any` can be temporarily used in places where types aren't yet known or representable +- If an external package doesn't yet have typings and you want to use `any` pending adding a `.d.ts` for it +- You're working with particularly complex or nuanced code that can't yet be represented in the TypeScript type system ## Related To @@ -140,4 +148,5 @@ and you want to be able to specify `any`. ## Further Reading -- TypeScript [any type](https://www.typescriptlang.org/docs/handbook/basic-types.html#any) +- TypeScript [`any` type documentation](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any) +- TypeScript [`unknown` type release notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-0.html#new-unknown-top-type)