orphants

Find and kill unused TypeScript types across your entire codebase. Zero config. One command.

Documentation · Contributing · License

---

Table of Contents

• Features
• Getting started
• Usage
• CI integration
• Programmatic API
• How it works
• Comparison
• FAQ
• Development
• Contributing
• Changelog
• License

---

Features

• Zero config, point at a path and orphants discovers tsconfig.json automatically
• Dead type detection, finds unused type, interface, and enum declarations
• Auto-fix, remove unused types in place with --fix
• CI-ready, exit code 1 when dead types exist, built for pull request gates
• JSON output, machine-readable results for scripts and dashboards
• Export analysis, optionally flag exported types with no external consumers
• Ignore globs, skip legacy or generated folders with --ignore
• Safe by default, preserves re-exports, JSDoc references, and declaration merging
• Programmatic API, use as a library, not just a CLI
• Local only, all analysis runs on your machine, nothing is uploaded
• Free, open source under MIT

Knip finds unused exports. orphants finds unused type declarations, including types never referenced anywhere, even in the same file.

---

Getting started

npm

npx orphants ./src

Install as a dev dependency

npm install -D orphants

Example output

npx orphants ./src

Found 847 types across 134 files
✗ 203 unused types detected

  UserResponseDTO     src/types/api.ts:14
  LegacyAuthPayload   src/auth/types.ts:89
  OldCartItem         src/cart/legacy.ts:3
  AdminPermissionMap  src/rbac/types.ts:201
  ...

Run with --fix to remove them

Remove dead types

npx orphants ./src --fix

✓ Removed 203 unused types
✓ 134 files cleaned

Requirements

• Node.js 18+
• A TypeScript project with a discoverable tsconfig.json
• Linux, macOS, or Windows

---

Usage

orphants <path> [options]

Option	Description
--project, -p	Path to a specific tsconfig.json
--fix	Remove unused types in place
--json	Output results as JSON
--stats-only	Print summary counts only, no per-type list
--ignore <glob>	Glob pattern of files to skip (repeatable)
--include-exported	Also flag exported types with no external consumers
--ci	Exit with code 1 if any unused types are found

# Scan a directory or file
npx orphants ./src
npx orphants ./src/types/api.ts

# Fail CI when dead types exist
npx orphants ./src --ci

# Flag exported types nobody imports
npx orphants ./src --include-exported

# Remove dead types (review the diff before merging)
npx orphants ./src --fix

# Skip legacy folders
npx orphants ./src --ignore "**/legacy/**"

# Use a specific tsconfig (monorepos, nested configs)
npx orphants ./src --project ./packages/app/tsconfig.json

# Compact output for scripts
npx orphants ./src --stats-only

# JSON output
npx orphants ./src --json

---

CI integration

- name: Check for unused types
  run: npx orphants ./src --ci

---

Programmatic API

import { findUnusedTypes, removeUnusedTypes } from "orphants";

const result = await findUnusedTypes({ path: "./src" });
console.log(result.stats);
console.log(result.unused);

const { fixResult } = await removeUnusedTypes({ path: "./src" });
console.log(fixResult.removedCount);

---

How it works

orphants uses ts-morph for AST analysis. No regex, no guesswork.

1. Scan, collect every type, interface, and enum (skips .d.ts)
2. Resolve, findReferencesAsNodes() per declaration with safety rules
3. Report, human-readable or JSON output
4. Remove, optional in-place deletion via --fix

Protected from removal

• Re-exports (export { Foo }, export * from)
• JSDoc references (@param, @returns, {@link})
• Declaration merging (multiple interface Foo blocks)
• Ambient .d.ts declarations

v1 limitations

• Single tsconfig scope (no cross-package monorepo analysis)
• Template-literal-type internals out of scope

---

Comparison

Tool	Unused exports	Unused type / interface / enum
tsc --noUnusedLocals	No	No
ts-prune / ts-unused-exports	Yes	No
Knip	Yes	No
orphants	No	Yes

---

FAQ

How is this different from Knip or ts-prune?
Those tools focus on unused exports. orphants targets type declarations that are never referenced, including non-exported aliases in the same file.

Will --fix break my code?
Only declarations with zero references are removed, after safety checks. Prefer --ci in PRs and --fix in dedicated cleanup PRs.

Does it upload my source code?
No. Everything runs locally.

---

Development

git clone https://github.com/false200/orphants.git
cd orphants
npm install
npm test
npm run build
node dist/cli.js ./src

---

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

Fork the repo, add your changes with tests, and open a pull request.

---

Changelog

See CHANGELOG.md for release history.

---

License

This project is open-source software licensed under the MIT license.