ast-grep for TypeScript & React
The wrong defaults a capable model hits when pointing ast-grep at .ts/.tsx code — mostly cases where a rule silently matches nothing because the language or a node kind was guessed wrong. This skill assumes you already know ast-grep's rule mechanics (patterns, meta-variables, all/any/has/inside, constraints); it corrects only what TypeScript and React add on top.
For general ast-grep rule-writing mechanics, use the companion ast-grep skill.
When to Apply
- Writing an ast-grep pattern or YAML rule whose target is
.ts or .tsx code
- Searching for JSX elements, props, React hooks, imports, or TS type constructs
- Building a codemod that rewrites JSX or TypeScript (rename a component, strip
React.FC, migrate imports)
- A rule "matches nothing" on TSX and you don't know why (usually the language or a node kind)
- Driving ast-grep programmatically from a JS/TS script via
@ast-grep/napi
First moves when a TS/React rule misbehaves
- Check the language. JSX-bearing files must run under
tsx, never typescript. This is the single most common cause of silent no-match. See lang-tsx-for-jsx.
- Debug the pattern's AST.
ast-grep run --pattern '<your pattern>' --lang tsx --debug-query=ast on a real snippet shows the node kinds and reveals ERROR nodes. Trust this over guessed kind names.
- Wrap fragments. If the pattern is an attribute, prop, or type annotation, it needs
context + selector. See ctx-fragment-context-selector.
Rule Categories
| # |
Category |
Prefix |
Covers |
| 1 |
Language Selection |
lang |
tsx-vs-typescript split, scanning .ts + .tsx, languageGlobs |
| 2 |
Fragment Matching |
ctx |
context/selector for JSX attrs, props, type annotations |
| 3 |
JSX Node Kinds |
jsx |
self-closing vs paired elements, attribute-value metavariables |
| 4 |
TypeScript Constructs |
ts |
type-only imports, as casts, React.FC generics |
| 5 |
Rewrites & Codemods |
fix |
re-emitting JSX metavars so children/props aren't dropped |
| 6 |
Programmatic Use |
napi |
@ast-grep/napi Lang.Tsx, NapiConfig shape |
Quick Reference
1. Language Selection (lang)
lang-tsx-for-jsx — Use tsx for any JSX; typescript parses JSX as ERROR and matches nothinglang-scan-ts-and-tsx — Cover both .ts and .tsx; languageGlobs for reuse (+ the <T>-cast caveat)
2. Fragment Matching (ctx)
ctx-fragment-context-selector — Wrap fragments (attrs, props, type annotations) in context/selector
3. JSX Node Kinds (jsx)
jsx-self-closing-vs-paired — <X/> and <X></X> are different kinds; match both with anyjsx-attribute-metavars — Metavariables must sit in a valid attribute-value position
4. TypeScript Constructs (ts)
ts-type-only-imports — Distinguish import type and inline type from value importsts-as-expression-casts — Match casts as as_expression, not angle bracketsts-generic-react-fc — Strip React.FC by targeting the type annotation
5. Rewrites & Codemods (fix)
fix-jsx-rewrite-completeness — Re-emit $$$PROPS/$$$CHILDREN or they're deleted
6. Programmatic Use (napi)
napi-lang-tsx-findall — Parse with Lang.Tsx; findAll takes a NapiConfig
How to Use
Read the individual reference file for the decision you're making — each is self-contained with a canonical example. references/_sections.md defines the categories; AGENTS.md is the full compiled index.
Related Skills
ast-grep — general ast-grep rule-writing mechanics (patterns, composition, constraints, testing). This skill layers TS/React specifics on top of it.
1---2name: ast-grep-typescript-react3description: Use this skill when writing, debugging, or reviewing ast-grep patterns, YAML rules, or codemods against TypeScript or React (.ts/.tsx) code — searching for JSX elements, props, hooks, imports, or type constructs, and rewriting them. Covers the TS/React-specific traps — the tsx-vs-typescript language split, JSX and TypeScript node kinds, fragment matching, rewrites, and the @ast-grep/napi API. Complements the general-purpose ast-grep skill (rule mechanics) — reach for this one whenever the target code is TypeScript or React.4---5
6# ast-grep for TypeScript & React
7
8The wrong defaults a capable model hits when pointing ast-grep at `.ts`/`.tsx` code — mostly cases where a rule **silently matches nothing** because the language or a node kind was guessed wrong. This skill assumes you already know ast-grep's rule mechanics (patterns, meta-variables, `all`/`any`/`has`/`inside`, constraints); it corrects only what TypeScript and React add on top.
9
10For general ast-grep rule-writing mechanics, use the companion `ast-grep` skill.
11
12## When to Apply
13
14- Writing an ast-grep pattern or YAML rule whose target is `.ts` or `.tsx` code
15- Searching for JSX elements, props, React hooks, imports, or TS type constructs
16- Building a codemod that rewrites JSX or TypeScript (rename a component, strip `React.FC`, migrate imports)
17- A rule "matches nothing" on TSX and you don't know why (usually the language or a node kind)
18- Driving ast-grep programmatically from a JS/TS script via `@ast-grep/napi`
19
20## First moves when a TS/React rule misbehaves
21
221. **Check the language.** JSX-bearing files must run under `tsx`, never `typescript`. This is the single most common cause of silent no-match. See [`lang-tsx-for-jsx`](references/lang-tsx-for-jsx.md).
232. **Debug the pattern's AST.** `ast-grep run --pattern '<your pattern>' --lang tsx --debug-query=ast` on a real snippet shows the node kinds and reveals `ERROR` nodes. Trust this over guessed kind names.
243. **Wrap fragments.** If the pattern is an attribute, prop, or type annotation, it needs `context` + `selector`. See [`ctx-fragment-context-selector`](references/ctx-fragment-context-selector.md).
25
26## Rule Categories
27
28| # | Category | Prefix | Covers |
29|---|----------|--------|--------|
30| 1 | Language Selection | `lang` | tsx-vs-typescript split, scanning `.ts` + `.tsx`, `languageGlobs` |
31| 2 | Fragment Matching | `ctx` | `context`/`selector` for JSX attrs, props, type annotations |
32| 3 | JSX Node Kinds | `jsx` | self-closing vs paired elements, attribute-value metavariables |
33| 4 | TypeScript Constructs | `ts` | type-only imports, `as` casts, `React.FC` generics |
34| 5 | Rewrites & Codemods | `fix` | re-emitting JSX metavars so children/props aren't dropped |
35| 6 | Programmatic Use | `napi` | `@ast-grep/napi` `Lang.Tsx`, `NapiConfig` shape |
36
37## Quick Reference
38
39### 1. Language Selection (lang)
40- [`lang-tsx-for-jsx`](references/lang-tsx-for-jsx.md) — Use tsx for any JSX; typescript parses JSX as ERROR and matches nothing
41- [`lang-scan-ts-and-tsx`](references/lang-scan-ts-and-tsx.md) — Cover both `.ts` and `.tsx`; `languageGlobs` for reuse (+ the `<T>`-cast caveat)
42
43### 2. Fragment Matching (ctx)
44- [`ctx-fragment-context-selector`](references/ctx-fragment-context-selector.md) — Wrap fragments (attrs, props, type annotations) in context/selector
45
46### 3. JSX Node Kinds (jsx)
47- [`jsx-self-closing-vs-paired`](references/jsx-self-closing-vs-paired.md) — `<X/>` and `<X></X>` are different kinds; match both with `any`
48- [`jsx-attribute-metavars`](references/jsx-attribute-metavars.md) — Metavariables must sit in a valid attribute-value position
49
50### 4. TypeScript Constructs (ts)
51- [`ts-type-only-imports`](references/ts-type-only-imports.md) — Distinguish `import type` and inline `type` from value imports
52- [`ts-as-expression-casts`](references/ts-as-expression-casts.md) — Match casts as `as_expression`, not angle brackets
53- [`ts-generic-react-fc`](references/ts-generic-react-fc.md) — Strip `React.FC` by targeting the type annotation
54
55### 5. Rewrites & Codemods (fix)
56- [`fix-jsx-rewrite-completeness`](references/fix-jsx-rewrite-completeness.md) — Re-emit `$$$PROPS`/`$$$CHILDREN` or they're deleted
57
58### 6. Programmatic Use (napi)
59- [`napi-lang-tsx-findall`](references/napi-lang-tsx-findall.md) — Parse with `Lang.Tsx`; `findAll` takes a `NapiConfig`
60
61## How to Use
62
63Read the individual reference file for the decision you're making — each is self-contained with a canonical example. [references/_sections.md](references/_sections.md) defines the categories; [AGENTS.md](AGENTS.md) is the full compiled index.
64
65## Related Skills
66
67- `ast-grep` — general ast-grep rule-writing mechanics (patterns, composition, constraints, testing). This skill layers TS/React specifics on top of it.
pproenca