Point it at one file and it reports every exported function, class, property, type, interface, enum, default export, and re-export it can resolve through the selected tsconfig.json.

Install#

bun install

For local development, link the CLI:

bun link

Then use tsref from another project:

tsref src/client.ts --project tsconfig.json

Usage#

tsref <file> [--project <tsconfig>] [--summary-only]

Options:

--project <path>   Path to tsconfig.json
--summary-only     Print only the export summary table
--unused           Show only exports with zero external references
--no-imports       Exclude import declarations from reference counts
--imports-only     Fast mode that counts only imports and re-exports
--diagnostics      Include TypeScript diagnostic count
--help             Print usage
--version          Print version

If --project is omitted, tsref searches upward from the current working directory for tsconfig.json.

Examples#

Analyze one file:

tsref src/stores/securityStore.ts --project tsconfig.json

Print only the table:

tsref src/stores/securityStore.ts --summary-only

Find unused exports:

tsref src/stores/securityStore.ts --unused

Ignore import declarations when counting references:

tsref src/stores/securityStore.ts --no-imports

Use the fastest dependency-level scan:

tsref src/stores/securityStore.ts --imports-only

Output#

The default report starts with a compact summary table:

tsref test/fixtures/basic/api.ts
project test/fixtures/basic/tsconfig.json

6 exports | 12 external refs | 2 internal refs

export        kind      external  internal  status
usedFunction  function         3         1  used
default       function         2         0  used
value         const            3         0  used
mutable       let              2         1  used
internalOnly  function         2         0  used
unusedHelper  function         0         0  unused

Detailed sections then show where each export is referenced:

allVpcs property
declared src/stores/securityStore.ts:20:3
external (8)
  read      src/pages/billing/hooks/useEntitlements.tsx:31:22
  read      src/pages/security/vpc/VpcPage.tsx:50:58
internal (3)
  write     src/stores/securityStore.ts:54:33
  read      src/stores/securityStore.ts:85:69

external references are outside the target file. internal references are inside the target file.

Declaration locations are shown separately and are not counted as references. This means an unused export may show one result in an editor's "find all references" view but still appear as external 0 and internal 0 in tsref.

Reference Kinds#

tsref classifies references into these buckets:

import: import declarations
re-export: export declarations that forward a symbol
call: function or method calls
construct: new expressions
read: runtime reads
write: assignments and updates
type: type-only positions
jsx: JSX element or attribute usage
unknown: references where the context is ambiguous

Performance Modes#

The default mode uses TypeScript's language-service reference engine for editor-like accuracy.

Use faster modes when you do not need every location:

tsref src/file.ts --summary-only

Counts references without rendering detailed sections.

tsref src/file.ts --unused

Uses a cheap first pass to find exports with zero external references, then renders details only for those exports.

tsref src/file.ts --imports-only

Counts only imports and re-exports using a syntax-level dependency scan. This is the fastest mode, but it does not include calls, reads, writes, JSX usage, or type references after import.

tsref src/file.ts --no-imports

Keeps full analysis but removes import declarations from counts and details.

Development#

Run tests:

bun test

Run typecheck:

bun run typecheck

Run the CLI without linking:

bun src/index.ts test/fixtures/basic/api.ts --project test/fixtures/basic/tsconfig.json

Configure Feed