TypeScript LSP Skill

Purpose

This skill provides TypeScript Language Server Protocol integration for exploring and understanding TypeScript/JavaScript codebases.

IMPORTANT: Prefer LSP tools over Grep/Glob when working with *.ts , *.tsx , *.js , *.jsx files. LSP provides type-aware results that understand imports, exports, and symbol relationships.

Use these tools to:

• Explore codebases - Find symbols, understand module structure, discover implementations

• Find references - Type-aware search across the entire codebase (better than grep for symbols)

• Understand types - Get full type signatures, generics, and documentation

• Verify before editing - Check all usages before modifying or deleting exports

• Navigate code - Jump to definitions, find implementations

When to Use Each Tool

Tool Purpose

Glob Find files by pattern

Grep Search text content

lsp-find Search TypeScript symbols

lsp-hover Get type info + TSDoc documentation

lsp-refs Find all references to a symbol

lsp-analyze Batch analysis of file structure

LSP vs Grep/Glob

Task Use LSP Use Grep/Glob

Find all usages of a function/type ✅ lsp-refs

❌ Misses re-exports, aliases

Search for a symbol by name ✅ lsp-find

❌ Matches strings, comments

Get type signature + TSDoc ✅ lsp-hover

❌ Not possible

Understand file exports ✅ lsp-analyze --exports

❌ Doesn't resolve re-exports

Find files by pattern ❌ ✅ Glob

Search non-TS files (md, json) ❌ ✅ Grep

Search for text in comments/strings ❌ ✅ Grep

When to Use

Exploring code (prefer LSP):

• Run lsp-find to search for symbols across the workspace

• Run lsp-symbols to get an overview of file structure

• Run lsp-analyze --exports to see what a module provides

Before editing code:

• Run lsp-references to find all usages of a symbol you plan to modify

• Run lsp-hover to verify current type signatures

Before writing code:

• Run lsp-find to search for similar patterns or related symbols

• Run lsp-hover on APIs you plan to use

Path Resolution

All scripts accept three types of file paths:

• Absolute paths: /Users/name/project/src/file.ts

• Relative paths: ./src/file.ts or ../other/file.ts

• Package export paths: my-package/src/module.ts (resolved via Bun.resolve() )

Package export paths are recommended for portability and consistency with the package's exports field.

Scripts

Individual Scripts

lsp-hover

Get type information at a specific position.

bunx @plaited/development-skills lsp-hover <file> <line> <char>

Arguments:

• file : Path to TypeScript/JavaScript file

• line : Line number (0-indexed)

• char : Character position (0-indexed)

Example:

bunx @plaited/development-skills lsp-hover src/utils/parser.ts 42 10

lsp-symbols

List all symbols in a file.

bunx @plaited/development-skills lsp-symbols <file>

Example:

bunx @plaited/development-skills lsp-symbols src/utils/parser.ts

lsp-references

Find all references to a symbol.

bunx @plaited/development-skills lsp-refs <file> <line> <char>

Example:

bunx @plaited/development-skills lsp-refs src/utils/parser.ts 42 10

lsp-find

Search for symbols across the workspace.

bunx @plaited/development-skills lsp-find <query> [context-file]

Arguments:

• query : Symbol name or partial name

• context-file : Optional file to open for project context

Example:

bunx @plaited/development-skills lsp-find parseConfig bunx @plaited/development-skills lsp-find validateInput src/lib/validator.ts

Batch Script

lsp-analyze

Perform multiple analyses in a single session for efficiency.

bunx @plaited/development-skills lsp-analyze <file> [options]

Options:

• --symbols, -s : List all symbols

• --exports, -e : List only exported symbols

• --hover <line:char> : Get type info (repeatable)

• --refs <line:char> : Find references (repeatable)

• --all : Run symbols + exports analysis

Examples:

Get file overview

bunx @plaited/development-skills lsp-analyze src/utils/parser.ts --all

Check multiple positions

bunx @plaited/development-skills lsp-analyze src/utils/parser.ts --hover 50:10 --hover 75:5

Before refactoring: find all references

bunx @plaited/development-skills lsp-analyze src/utils/parser.ts --refs 42:10

Common Workflows

Understanding a File

1. Get exports overview

bunx @plaited/development-skills lsp-analyze path/to/file.ts --exports

2. For specific type info, hover on interesting symbols

bunx @plaited/development-skills lsp-hover path/to/file.ts <line> <char>

Before Modifying an Export

1. Find all references first

bunx @plaited/development-skills lsp-refs path/to/file.ts <line> <char>

2. Check what depends on it

Review the output to understand impact

Finding Patterns

Search for similar implementations

bunx @plaited/development-skills lsp-find handleRequest bunx @plaited/development-skills lsp-find parseConfig

Pre-Implementation Verification

Before writing code that uses an API, verify its signature

bunx @plaited/development-skills lsp-hover path/to/api.ts <line> <char>

Output Format

All scripts output JSON to stdout. Errors go to stderr.

Hover output:

{ "contents": { "kind": "markdown", "value": "typescript\nconst parseConfig: (options: Options) => Config\n" }, "range": { "start": {...}, "end": {...} } }

Symbols output:

[ { "name": "symbolName", "kind": 13, "range": { "start": {...}, "end": {...} } } ]

Analyze output:

{ "file": "path/to/file.ts", "exports": [ { "name": "exportName", "kind": "Constant", "line": 139 } ] }

Performance

Each script invocation:

• Starts TypeScript Language Server (~300-500ms)

• Initializes LSP connection

• Opens document

• Performs query

• Closes and stops

For multiple queries on the same file, use lsp-analyze to batch operations in a single session.

Related Skills

• code-documentation: TSDoc standards for documentation