Docs: [consistent-type-imports] Revise recommended usage

[aaronadamsCA]

Before You File a Documentation Request Please Confirm You Have Done The Following...

• I have looked for existing open or closed documentation requests that match my proposal.
• I have read the FAQ and my problem is not listed.

Suggested Changes

The consistent-type-imports page specifically recommends that if you use verbatimModuleSyntax, you should turn off this rule:

Because there are some differences, using both this rule and verbatimModuleSyntax at the same time can lead to conflicting errors. As such we recommend that you only ever use one or the other -- never both.

But this rule does something very important that verbatimModuleSyntax does not: it makes sure you use import type for imports used only as types.

consistent-type-imports is concerned with exactly one thing - ensuring your value imports are used as values, warning you when your value imports aren't used as values. #6379 (comment)

So in this situation:

import { GraphQLSchema } from "graphql";

export class Foo {
  private readonly schema: GraphQLSchema;

  constructor(schema: GraphQLSchema) {
    this.schema = schema;
  }

  // …
}

If you enable verbatimModuleSyntax, oops, now you have a side-effect import of "graphql"—and all of the weird problems that brings (graphql/graphql-js#2801).

For this reason, I think it would be good to update the recommendations for this rule, since it can specifically help guard against unwanted side effects once verbatimModuleSyntax is enabled.

Affected URL(s)

https://typescript-eslint.io/rules/consistent-type-imports

Additional Info

No response