---
title: "TypeScript"
description: "Run evidence and boundary diagnostics automatically in every TypeScript project."
canonical_url: "https://vite-doctor.onmax.me/typescript"
---
# TypeScript

> Run evidence and boundary diagnostics automatically in every TypeScript project.

Vite Doctor activates its TypeScript rules automatically when the project contains a `tsconfig.json` or TypeScript source files. The recommended preset focuses on unsafe type claims and unvalidated runtime data.

## Install

Add Vite Doctor to any TypeScript project:

```bash
pnpm add -D vite-doctor
```

Run Doctor from the project root:

```bash
pnpm vite-doctor .
```

No framework option or TypeScript-specific configuration is required. JavaScript-only projects do not activate these rules.

## Use the strict preset

The strict preset adds opinionated checks for runtime narrowing, conditional object spreads, and undocumented type assertions:

```bash
pnpm vite-doctor . --extends auto,vite-doctor/typescript/strict
```

It runs every TypeScript rule except opt-in policy rules such as `typescript/strict/no-comments`, which only a `rules` entry turns on.

## Delete comments no tool reads

`typescript/strict/no-comments` (`TS0017`) reports comments that do not match a known directive or an allowed comment pattern. Comments that repeat the code can go stale when the code changes, and agents may read them as facts. The rule is opt-in: no preset turns it on, `strict` included. Name it in `doctor.config.json`:

```json [doctor.config.json]
{
  "rules": {
    "typescript/strict/no-comments": [
      "warn",
      {
        "allow": ["^\\s*provider-message-match:", "^\\s*@generated-by\\b"],
        "apiDocs": "exported"
      }
    ]
  }
}
```

When an agent adds Doctor to a project with the [Doctor skill](https://vite-doctor.onmax.me/.well-known/skills/doctor/SKILL.md), the skill turns this rule on at `warn` in the project's Doctor config and tells you how to turn it off. To turn it off, set `"typescript/strict/no-comments": "off"` or delete the entry. Doctor itself never turns the rule on: the same repository reports the same Diagnostics for an agent, a person, and CI.

It checks comments in `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, and `.cjs` files, in both `<script>` blocks of a Vue component, in Vue templates, and in JSX, including JavaScript-only projects. It also checks test code, which other Rules skip: files in `test`, `tests`, `__tests__`, and `test-utils` folders, and `*.test.*` and `*.spec.*` files. It does not check `<style>` blocks or the other files Doctor does not scan, such as fixtures, snapshots, and generated files.

To keep comments in tests, turn the rule off for them with `overrides`:

```json [doctor.config.json]
{
  "rules": { "typescript/strict/no-comments": "warn" },
  "overrides": [
    {
      "files": [
        "**/{test,tests,__tests__,test-utils}/**",
        "**/*.{test,spec}.{ts,tsx,mts,cts,js,jsx,mjs,cjs,vue}"
      ],
      "rules": { "typescript/strict/no-comments": "off" }
    }
  ]
}
```

### What the rule keeps

The rule recognizes these common exemptions:

- compiler, linter, formatter, and coverage directives: `@ts-`, `eslint`, `/* global */`, `/* exported */`, `oxlint-`, Doctor inline suppressions, `prettier-ignore`, `oxfmt-ignore`, `dprint-ignore`, `biome-ignore`, `v8 ignore`, `c8 ignore`, `istanbul ignore`, `@vitest-environment`, `@jest-environment`, and `@jsx` pragmas;
- bundler annotations: `#__PURE__`, `#__NO_SIDE_EFFECTS__`, `@vite-ignore`, and webpack magic comments;
- triple-slash references, `/*!` banners, `@license` and `@preserve` comments, source map comments, and the `#!` line;
- SAFETY notes and the comments that directly continue them, in any form that `typescript/strict/require-safety-comment-for-type-assertion` (`TS0008`) accepts, so the two rules never disagree;
- semantic JSDoc in JavaScript, such as `@type`, `@template`, and `@readonly`, and `@internal` annotations used by TypeScript's `stripInternal`, even with `apiDocs: "none"`;
- Vue template directives such as `@vue-ignore`, `@vue-expect-error`, `@vue-skip`, and `@vue-generic`, as well as shared directives such as `<!-- eslint-disable-next-line -->`.

### Options

- `allow`: regular expression sources, matched against the comment text without its delimiters. Use it for comments that the project's own tools read. An invalid pattern stops the run with `DOC0020`.
- `apiDocs`: `"exported"` (the default) keeps a JSDoc block directly before an exported declaration and before the members of an exported declaration: interface, type literal, and class members, enum members, and union members. `"none"` reports those too.

Use `overrides` to change the options for some paths, for example to keep API docs only in published packages:

```json [doctor.config.json]
{
  "rules": { "typescript/strict/no-comments": ["warn", { "apiDocs": "none" }] },
  "overrides": [
    {
      "files": ["packages/*/src/**"],
      "rules": { "typescript/strict/no-comments": ["warn", { "apiDocs": "exported" }] }
    }
  ]
}
```

### Adopt it in an existing codebase

Run it with `--since <ref>` so it reports only comments on changed lines. It needs no baseline file:

```bash
pnpm vite-doctor . --since origin/main --max-warnings 0
```

A full run without `--since` also checks old comments. Code that is moved or reformatted brings its comments into the diff. The rule sets each finding's fingerprint from the file path and the comment text, so a `--baseline` file also survives renamed functions and new code above a comment, but rewording a comment makes it new.

### Classify before deleting

First check whether a project tool consumes the comment. If it does, add an `allow` pattern instead of deleting it. Otherwise, put it in one class before you delete it:

- **Tautology**: it repeats what the code says. Delete it.
- **Stale**: it is no longer true. Delete it.
- **Excuse**: it allows a workaround. File an issue for the workaround, then delete it.
- **Decision Record**: it records a non-obvious decision the code cannot show. Move it to the project's decision log, then delete it.

When removing a script or JSX comment, keep its line breaks (for example, after `return`) and leave a space if the comment separates tokens (for example, `const/**/value`).

### Delete them with `--unsafe-fix`

Classify first. The fix deletes every reported comment it can delete without changing the code, and it cannot tell a tautology from a decision or an excuse you still need to move. That makes it unsafe: plain `--fix` never applies it. With the rule named in `doctor.config.json`, run it alone:

```bash
pnpm vite-doctor . --rules typescript/strict/no-comments --unsafe-fix
```

The fix removes a standalone script comment together with its line, and a trailing script comment together with the space before it. It removes a JSX comment with its `{}` container. In Vue templates it deletes only comments that touch element or container boundaries on both sides. Doctor then runs again and reports the comments it left, without a fix:

- a block comment that spans lines with code on both sides, because its line break can end a statement after `return` or `throw`;
- a JSX comment whose removal could change rendered text or merge separate text children into one, including text with unusual whitespace and runs where multiple edits would have to be applied together;
- a Vue template comment that is a component's only child, because it can supply the default slot;
- a Vue template comment next to text, an interpolation, another comment, or whitespace, or inside `<pre>`; Vue's `whitespace` option can preserve whitespace even on otherwise empty lines;
- JSX comments that share a line with each other and with other code;
- any reported comment in a file with a retained tooling directive, checked JSDoc annotation, public API JSDoc, or comment matched by `allow`. Doctor cannot guarantee that deleting a nearby comment preserves what the retained comment applies to. A standalone license identifier does not block fixes.

## Run one rule

Use a TypeScript rule ID without selecting a framework:

```bash
pnpm vite-doctor . --rules typescript/boundaries/no-unvalidated-deserialization
```

Doctor returns compact structured output automatically in recognized agent runtimes. Use `--format agent` for a fixed agent contract or `--format json` for the complete machine report.

---

- [TypeScript rules](https://vite-doctor.onmax.me/typescript/rules)
- [CLI](https://vite-doctor.onmax.me/cli)


## Sitemap

See the full [sitemap](https://vite-doctor.onmax.me/sitemap.md) for all pages.
