tsro

TypeScript Remove Orphaned (tsro) is a CLI utility and library for TypeScript projects that detects and removes files containing invalid imports — imports that refer to nonexistent entities or nonexistent modules.

Features

🕵️ Find unused code

The utility scans the entire project using information from tsconfig.json and the TypeScript Compiler API to identify files that contain imports referencing non-existent modules or entities. These files are considered “orphaned” because their imports are broken, and they are often leftover from removed or refactored code.

🗑️ Remove unused code automatically

When the --write flag is enabled, tsro deletes the files containing broken imports from the project, helping keep the codebase clean and free of leftover or obsolete files.

🚀 Works out of the box

The tool requires no separate configuration or setup. A valid tsconfig.json is enough to analyze the project, making it easy to integrate and use in existing codebases.

Installation

npm install -g tsro

TypeScript is a peer dependency.

Quick Start

1. 🔍 Check your tsconfig.json – Make sure include and exclude are configured thoroughly so that tsro can correctly detect orphan files.

2. 🚀 Execute – Run tsro. Use --write to delete orphaned files.

tsro

Usage

CLI

Usage: tsro [options]

Options:
  -v, --version          output the version number
  -p, --project <file>   path to tsconfig file
  -w, --write            delete orphaned files
  --no-ignoreLibImports  no ignore lib imports
  -h, --help             display help for command

Examples:
  # Write changes in place
  tsro --write

  # Check orphan files for a project with a custom tsconfig.json
  tsro --project tsconfig.test.json

  # Check orphan files without ignoring lib imports
  tsro --no-ignoreLibImports

-p, --project

Specifies the tsconfig.json that is used to analyze your codebase. Defaults to tsconfig.json in your project root.

tsro --project tsconfig.test.json

-w, --write

By default, tsro does not delete anything, it only reports orphan files. The --write flag enables actual deletion of these files from the project.

[!WARNING] This will delete files. Using it in a git controlled environment is highly recommended.

--no-ignoreLibImports

By default, tsro skips imports from libraries to avoid resolution errors — in some cases, the tool may incorrectly determine that a library doesn’t exist or doesn’t export the used entity. The --no-ignoreLibImports flag disables this behavior and enables analysis of library imports.

[!WARNING] May cause valid imports to be mistakenly flagged as unresolved or missing.

JavaScript API

Alternatively, you can use the JavaScript API to execute tsr.

import { tsro } from 'tsro';

await tsro({
  mode: 'check',
  ignoreLibImports: false,
}).catch(() => {
  process.exitCode = 1;
});

The project path and/or the custom tsconfig.json can be manually specified.

await tsr({
  mode: 'check',
  configFile: 'tsconfig.sample.json',
  projectRoot: '/path/to/project',
});

Check the type definition import type { Config } from 'tsro for all of the available options.

Examples

tsro is useful for cleaning up test, spec, and story files that remain after removing the tested files or entities using other tools (e.g., knip --production or tsr).

A common use case is running tsro with a separate config that includes only test and story files to delete unused test files:

tsro -p tsconfig.test.json -w

Example tsconfig.test.json:

{
  "include": [
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/*.stories.ts"
  ]
}

License

MIT © Pepetka. See the LICENSE file for details.