# Ub TS

> Use this skill for TypeScript typing and compiler configuration in Node, bundler, library, Vue, Nuxt, and other TypeScript projects. Apply it when the task involves tsconfig, module or moduleResolution behavior, compiler flags, emitted types, type errors, project-wide TS modernization, or boundary typing.

- Skill: `robert-hoffmann/ub-ts` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add robert-hoffmann/ub-ts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/robert-hoffmann/ub-ts/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: robert-hoffmann (https://skillmd.com/u/robert-hoffmann)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/robert-hoffmann/ub-ts

---


# UB TS

## Overview

Use this skill to enforce latest stable TypeScript modern defaults and patterns across app and library codebases. Generate modern-only output for new code, and allow legacy retention only as a bounded migration exception.

Implement against the detected project TypeScript and runtime truth, but bias
design toward forward-compatible migration rather than compatibility layers or
legacy fallbacks.

## Bundled Assets

This skill ships reusable `tsconfig` starter scaffolding and an optional ESLint
flat-config starter under `assets/`, plus a deterministic helper under
`scripts/`.

Use them when a repository wants this house-style starting point and does not
yet have active TypeScript config of its own.

## Load References On Demand

- Read `references/ts-modern-patterns.md` for archetype selection, tsconfig baselines, and modern typing patterns.
- Read `references/ts-legacy-to-modern-migration.md` for old-to-new migrations, banned patterns, and exception handling.
- Read `references/ts-config-resolution.md` when local TypeScript config
  discovery, starter scaffolding, or optional ESLint support matters.
- Read `references/task-bundle.md` only when the target repository wants an
  optional Task-based automation overlay for this skill's starter profile.
- Use `scripts/scaffold_ts_baseline.py` with `assets/tsconfig-template/` and
  `assets/eslint-template/` when a target repository needs a deterministic
  starter instead of ad hoc config creation.

## Skill Coordination

- Co-load this skill with `ub-vuejs` or `ub-nuxt` when TypeScript issues live
  inside framework projects.
- Defer framework runtime, routing, and app-structure decisions to the sibling
  skill that owns them.

## Core Workflow

1. Detect the project archetype from `package.json`, lockfiles, runtime targets, build tooling, and existing `tsconfig*.json` files.
2. Choose module strategy that matches runtime truth:
   - Node runtime: `module` as `node20` or `nodenext`
   - Bundler runtime: `moduleResolution` as `bundler` with `module` as `esnext`
   - Library publishing: prefer Node-faithful resolution for compatibility checks
   - Type-stripping runtime: enforce erasable TypeScript subset
3. Compare official guidance, repo truth, and observed code reality for
   non-trivial or version-sensitive recommendations.
4. Surface `OFFICIAL_CONFLICT` when authoritative sources, repo truth, or live
   code reality materially disagree on a non-trivial recommendation.
5. Surface `UNVERIFIED` when a non-trivial claim could not be confirmed in
   official sources after targeted research.
6. Apply strict safety baseline and module hygiene defaults from `references/ts-modern-patterns.md`.
7. Implement modern type patterns first (`satisfies`, `const` type parameters, `NoInfer`, discriminated unions, explicit boundary typing).
8. Reject legacy output for new code and apply migration mapping from `references/ts-legacy-to-modern-migration.md` when touching existing code.
9. Validate with available typecheck, lint, tests, and build commands in the target project.
10. If a repository wants this baseline but lacks TypeScript config, scaffold
    the bundled starter and explain the remaining repo-local adaptations.

## Version & Research Policy

- Target the latest stable release of TypeScript.
- Detect the project's actual TypeScript version from `package.json` and lockfiles.
- Use web search to verify current best practices, API availability, and migration guidance against official TypeScript documentation.
- Treat repo truth as the gold implementation standard when deciding what can
  actually ship safely in the current project.
- Treat official TypeScript docs as the preferred guidance baseline for
  forward-looking design and migration-ready patterns.
- If official guidance and repo truth diverge materially on a non-trivial
  recommendation, surface `OFFICIAL_CONFLICT`, implement the repo-safe path,
  and explain the migration path.
- If official sources disagree with each other on a non-trivial recommendation,
  also surface `OFFICIAL_CONFLICT` instead of silently collapsing the
  disagreement.
- If a non-trivial claim cannot be confirmed in official sources after targeted
  research, mark it `UNVERIFIED` or avoid presenting it as settled guidance.
- Keep conflict and uncertainty disclosure scoped to non-trivial,
  version-sensitive, or contested guidance rather than trivial edits.
- Do not emit beta-only syntax unless the user explicitly requests it.
- When the project's installed version is behind latest stable, note the version gap and recommend an upgrade path.
- Inspect the host repository's `AGENTS.md` or equivalent instructions when
  present for project-specific version policy and tooling; do not assume it
  contains this catalog's defaults.
- Do not hardcode version numbers in generated guidance — keep recommendations evergreen.

## Freshness Review

- Volatility: high
- Review recommendation: review on touch and during periodic maintenance, targeting a quarterly rhythm when practical.
- Trigger signals: TypeScript release changes, compiler-flag behavior shifts, new module-resolution guidance, or runtime-platform updates that affect tsconfig strategy.
- Enforcement: advisory only; freshness should inform review priority, not become a blocking requirement by itself.
- Stable core: runtime-faithful module strategy, strict typing, and explicit boundary modeling remain the durable guidance even when compiler defaults evolve.

## Implementation Rules

### Project Archetype and Modules

- Decide archetype before changing compiler options.
- Keep module settings runtime-faithful, not preference-driven.
- Keep `moduleDetection` as `force` unless a known compatibility constraint requires otherwise.

### Import and Export Hygiene

- Keep `verbatimModuleSyntax` enabled.
- Use `import type` and `export type` for type-only symbols.
- Keep side-effect imports explicit and resolvable.

### Type System Patterns

- Prefer `satisfies` to validate shapes without widening literals.
- Prefer `const` type parameters in reusable APIs that benefit from literal preservation.
- Use built-in `NoInfer` when inference must be constrained.
- Model state with discriminated unions when behavior depends on variants.
- Use `unknown` at trust boundaries, then narrow with validation.

### Compiler Baseline

- Keep `strict: true`.
- Keep `noUncheckedIndexedAccess: true`.
- Keep `exactOptionalPropertyTypes: true`.
- Enable `isolatedModules` in toolchain-mixed repos.
- Enable `isolatedDeclarations` for declaration-heavy library workflows.
- Use `noUncheckedSideEffectImports` when side-effect imports are present.

## Config Resolution And Scaffolding

Treat real project config as the source of truth:

1. inspect `tsconfig*.json`, `eslint.config.*`, `package.json`, and lockfiles
   first when they exist
2. match local runtime, bundler, and package-manager truth before choosing a
   starter
3. use the bundled `tsconfig` scaffold only when the repository lacks active
   config and wants this house-style baseline
4. treat the ESLint starter as optional strong-default support for TS repos,
   not as universal TypeScript policy
5. do not silently install dependencies or mutate CI as part of scaffolding

### Tradeoff Handling

- Use the shared `ub-quality` decision-analysis baseline for major TypeScript
  decisions.
- State TypeScript-specific pros and cons for each option, especially around
  correctness, compatibility, DX, and migration cost.
- Default to the safest modern option unless user constraints indicate otherwise.

## Legacy-Avoidance Guardrails

- Do not generate legacy experimental decorator patterns for new code.
- Do not generate `namespace`-centric architecture for new code.
- Do not rely on implicit type-only import elision.
- Do not use assertion-heavy shortcuts (`as any`, chained assertions) where narrowing is possible.
- Do not introduce legacy module ambiguity between ESM and CJS.

Migration-aware exception policy:

- Allow temporary legacy retention only for explicit compatibility constraints in existing code.
- Document exactly what is retained, why it is retained, and the concrete follow-up modernization step.
- Scope each exception narrowly and avoid introducing new dependency on retained legacy behavior.

## Output Requirements

When generating or reviewing code, include:

1. Environment note: detected archetype, runtime target, and toolchain context.
2. Source truth note: detected project version/toolchain reality and any
   material gap versus latest stable guidance.
3. Version note: TypeScript baseline and any intentional deviations.
4. Decision note: chosen module and compiler strategy with one alternative.
5. Tradeoff note: concise pros and cons for chosen path and rejected option.
6. Legacy note: removed legacy patterns or bounded exceptions with rationale.
7. Validation note: what checks were run and outcomes.
8. Conflict note when relevant: `OFFICIAL_CONFLICT` or `UNVERIFIED` with a
   concise explanation and the implementation consequence.

When this skill is used to scaffold TypeScript config into another repository,
also include:

1. which files were created or skipped
2. which archetype was chosen and one rejected alternative
3. which repo-local settings or dependencies still need adaptation
4. the exact next validation command to run

## Completion Checklist

- Latest stable TypeScript modern baseline is enforced.
- Project archetype was detected before config or code changes.
- Module strategy matches runtime behavior.
- Strict safety flags are enabled intentionally.
- New code avoids legacy patterns.
- Any retained legacy pattern is documented with a migration path.
- Typecheck and relevant project validations were executed when available.
- Any material official-source conflict or unverified non-trivial guidance is
  disclosed explicitly when relevant.
- Any scaffolded baseline was reported as a starter profile rather than silent
  repo policy.