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.

bash

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:

bash

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

lsp-symbols

List all symbols in a file.

bash

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

Example:

bash

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

lsp-references

Find all references to a symbol.

bash

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

Example:

bash

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

lsp-find

Search for symbols across the workspace.

bash

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:

bash

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.

bash

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:

bash

# 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

bash

# 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

bash

# 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

bash

# Search for similar implementations
bunx @plaited/development-skills lsp-find handleRequest
bunx @plaited/development-skills lsp-find parseConfig

Pre-Implementation Verification

bash

# 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:

json

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

Symbols output:

json

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

Analyze output:

json

{
  "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

typescript-lsp

NPX Install

SKILL.md Content

TypeScript LSP Skill

Purpose

When to Use Each Tool

LSP vs Grep/Glob

When to Use

Path Resolution

Scripts

Individual Scripts

lsp-hover

lsp-symbols

lsp-references

lsp-find

Batch Script

lsp-analyze

Common Workflows

Understanding a File

Before Modifying an Export

Finding Patterns

Pre-Implementation Verification

Output Format

Performance

Related Skills