---
name: twoslash-validator
description: Validate and fix two-slash TypeScript examples for aspire.dev. Use when adding or editing `twoslash` code fences, TypeScript AppHost samples, generated TypeScript API data, or failures from `pnpm test:unit:twoslash-blocks`.
---
# Two-slash Validator Skill
Use this skill to keep aspire.dev from shipping rendered two-slash error UI. Any TypeScript diagnostic in a `twoslash` code block renders an error box on the site, so diagnostics must be fixed rather than suppressed.
## When to use this skill
- Adding or editing a TypeScript code fence with the `twoslash` meta flag
- Updating TypeScript AppHost examples that import `'./.aspire/modules/aspire.mjs'`
- Refreshing `src/frontend/src/data/ts-modules/` or `src/frontend/src/data/twoslash/aspire.d.ts`
- Investigating failures from `pnpm test:unit:twoslash-blocks`
- Reviewing docs changes that affect TypeScript sample rendering
## Core rule
Do not add diagnostic allowlists or suppressions. A two-slash diagnostic is user-visible output on aspire.dev. Fix the docs sample, fix/regenerate the generated type surface, or remove the `twoslash` meta until the sample compiles cleanly.
## Validation workflow
Run commands from the repository root unless noted.
1. Ensure dependencies are installed:
```powershell
Set-Location -Path .\src\frontend
pnpm install --frozen-lockfile --prefer-offline
```
2. If TypeScript API JSON changed, regenerate the two-slash declaration bundle:
```powershell
pnpm twoslash-types
```
3. Run the two-slash block gate:
```powershell
pnpm test:unit:twoslash-blocks
```
4. If the test fails, read every reported file, line, block number, and `ts(...)` code. Fix every diagnostic before considering the work complete.
## Fix strategy
Use this order when deciding what to change:
1. **Docs sample bug:** If the TypeScript snippet calls the wrong API, uses the wrong argument shape, has a stale model name, or chains incompatible resources, fix the MDX sample.
2. **Generated type data stale:** If the sample matches the product API but `src/frontend/src/data/twoslash/aspire.d.ts` is stale, run `pnpm twoslash-types` and commit the regenerated bundle.
3. **Generator type-shape gap:** If regeneration is not enough because `scripts/generate-twoslash-types.ts` loses valid SDK shape, fix the generator and regenerate `aspire.d.ts`.
4. **Feature not representable yet:** If a correct sample cannot be represented by the current two-slash type data, remove the `twoslash` meta from that block and leave the code sample visible without two-slash rendering. Do not leave a rendered diagnostic.
## What not to do
- Do not reintroduce `KNOWN_TYPE_BUGS`, per-page diagnostic budgets, or equivalent allowlists.
- Do not disable `TWOSLASH_ENABLED` to make the test pass.
- Do not change `noErrorValidation` as a substitute for fixing diagnostics; it exists so the audit can collect all failures at once.
- Do not hide failures by changing the fence language away from TypeScript unless the sample is not TypeScript.
- Do not edit generated `aspire.d.ts` by hand; update the generator or source JSON and regenerate.
## Expected final checks
Before finishing a two-slash-related change, run:
```powershell
Set-Location -Path .\src\frontend
pnpm test:unit:twoslash-blocks
```
If you changed the generator, also run:
```powershell
pnpm test:unit:twoslash-types
```