What Is the `entryFiles` Configuration Option for Dead Code Detection in React Doctor?

The entryFiles option specifies which source files React Doctor should treat as entry points when performing dead-code analysis, preventing false positives for bootstrap files like src/index.tsx that are not imported by other modules but are legitimate starting points for your application.

React Doctor is a diagnostic tool for React applications that leverages Knip under the hood to detect unused code. When running dead-code analysis, the tool builds a dependency graph to identify orphaned files. The entryFiles configuration option ensures that your application's entry points—files that initiate the dependency chain but are never imported elsewhere—are correctly excluded from dead-code reports.

Why Dead Code Detection Needs Entry Points

Dead-code detection works by constructing a dependency graph of your codebase. Any file that is not reachable from a designated entry point is flagged as unused. By default, Knip only recognizes files that are explicitly imported somewhere in the project. This creates a blind spot for top-level files such as src/index.tsx, src/main.tsx, or custom bootstrap scripts that serve as the application entry point but are never imported by other modules.

Without explicit entry point configuration, these critical bootstrap files are mistakenly reported as dead code. The entryFiles option bridges this gap by forcing the analyzer to start its reachability walk from specified files, ensuring only truly orphaned code is flagged.

How entryFiles Works Under the Hood

React Doctor injects the specified entry files into Knip's configuration before invoking the analyzer. This happens in two key stages: configuration merging and scan orchestration.

Merging Configuration in run-knip.ts

The runKnip utility function in packages/react-doctor/src/utils/run-knip.ts handles the integration with Knip. When you provide entryFiles, the function merges them into Knip's entry configuration field:

// packages/react-doctor/src/utils/run-knip.ts
if (entryFiles && entryFiles.length > 0) {
  const parsedConfigForEntries = options.parsedConfig as Record<string, unknown>;
  const existingEntry = Array.isArray(parsedConfigForEntries.entry)
    ? (parsedConfigForEntries.entry as string[])
    : [];
  parsedConfigForEntries.entry = [...existingEntry, ...entryFiles];
}

This code checks for existing entries in the Knip configuration, converts them to an array if necessary, and appends the user-specified entryFiles. By modifying the parsedConfigForEntries.entry array directly, React Doctor ensures Knip treats these files as roots for its dependency graph traversal.

Orchestrating the Scan in scan.ts

The dead-code pass is initiated from packages/react-doctor/src/scan.ts, which forwards the entryFiles option to the runKnip utility:

// packages/react-doctor/src/scan.ts (excerpt)
const deadCodeDiagnostics = await runKnip(rootDirectory, entryFiles);

This separation of concerns allows scan.ts to focus on orchestrating the diagnostic process while run-knip.ts handles the Knip-specific configuration details. The CLI implementation in packages/react-doctor/src/cli.ts exposes the --entry-files flag, which populates this same option before reaching scan.ts.

Configuring Entry Files in Your Project

You can specify entry files through both the programmatic API and the command-line interface.

Programmatic API Usage

When invoking React Doctor programmatically via the scan function from @million/react-doctor, pass an array of paths to the entryFiles option:

import { scan } from '@million/react-doctor';

await scan({
  rootDirectory: '/my/project',
  // Files that start the import graph (e.g., the app entry point)
  entryFiles: ['src/index.tsx'],
  deadCode: true,          // enable dead-code detection
});

This approach is ideal for build scripts or custom tooling where you want to define entry points relative to your project structure dynamically.

CLI Usage

The React Doctor CLI exposes the --entry-files flag, which accepts comma-separated paths:

# Treat src/index.tsx and src/service-worker.ts as entry points

react-doctor --dead-code --entry-files src/index.tsx,src/service-worker.ts

If the flag is omitted, React Doctor falls back to Knip's default behavior, which may flag legitimate entry points as unused. Always specify your application's bootstrap files when running dead-code analysis to avoid false positives.

Summary

• The entryFiles option prevents false-positive dead-code reports for bootstrap files that are not imported by other modules.
• React Doctor merges specified entry files into Knip's configuration in packages/react-doctor/src/utils/run-knip.ts before analysis.
• The scan.ts module orchestrates the dead-code pass and forwards entryFiles to the underlying Knip integration.
• You can specify entry files programmatically via the scan() API or via the CLI using the --entry-files flag with comma-separated paths.
• Without this configuration, files like src/index.tsx are incorrectly flagged as unused because Knip only tracks explicitly imported modules by default.

Frequently Asked Questions

What happens if I don't specify entryFiles?

If you omit the entryFiles configuration, React Doctor relies on Knip's default behavior. Knip only recognizes files that are explicitly imported by other files in your project. Consequently, your application's entry points—such as src/index.tsx or src/main.tsx—will likely be reported as dead code because no other file imports them. Always specify entry files to ensure accurate analysis.

Can I specify multiple entry files?

Yes. The entryFiles option accepts an array of strings when using the programmatic API, or comma-separated values when using the CLI --entry-files flag. This is useful for applications with multiple entry points, such as separate main and service worker entry files, or monorepos with distinct package entry points.

How does React Doctor differ from running Knip directly?

React Doctor provides a React-specific wrapper around Knip with additional configuration defaults and integration points tailored for React applications. While you could run Knip directly, React Doctor handles the configuration merging—specifically the entryFiles injection—in packages/react-doctor/src/utils/run-knip.ts, and offers a unified diagnostic interface through scan.ts. This abstraction ensures React-specific heuristics and project structures are accounted for without manual Knip configuration.

Where is the entryFiles configuration processed in the source code?

The configuration is processed in three key locations: packages/react-doctor/src/cli.ts parses the CLI flag, packages/react-doctor/src/scan.ts passes the option to the analysis runner, and packages/react-doctor/src/utils/run-knip.ts merges the values into Knip's internal configuration object before invoking the dead-code detector.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}