Tsconfig hardening
Use this skill when
- The user wants to enable stricter TypeScript settings safely.
- A repository has a confusing
tsconfig chain that needs cleanup or consolidation.
- Module resolution, emit behavior, or workspace config drift is causing recurring TypeScript issues.
- The user wants to change TypeScript configuration even if that work may produce compiler errors that will need follow-on triage.
Do not use this skill when
- The task is to fix one local type error without changing project configuration.
- The build problem is mainly in Babel, bundler, or runtime tooling with no meaningful
tsconfig change.
- The repository intentionally uses a loose config and the user did not ask to harden it.
- The main task is now triaging the compiler errors caused by an earlier config change rather than changing config further.
Inputs to gather
Required before editing
- The active
tsconfig files and their extends chain.
- The repository's typecheck, build, and test commands.
- The current strictness posture, such as
strict, noImplicitAny, or noUncheckedIndexedAccess.
- Whether the project emits JavaScript, declarations, or typechecks only.
Helpful if present
- Baseline compiler error counts before changing flags.
- Whether the repository mixes ESM and CJS.
- Package-level overrides in a monorepo.
First move
- Inventory the
tsconfig chain and run tsc --showConfig or the nearest equivalent when available.
- Capture the current typecheck/build command and baseline compiler error count before changing flags.
- Separate configuration cleanup from code fixes so the diff explains itself.
- Pick one strictness or resolution problem to address first instead of flipping every flag at once.
Concrete config diffs
Base config before:
{
"compilerOptions": {
"strict": false,
"noImplicitAny": false
}
}
Base config after:
{
"compilerOptions": {
"strict": false,
"noImplicitAny": true
}
}
Use a single-flag step like this before considering strict: true; the umbrella switch is only safe when the blast radius is already understood.
Package override before:
{
"extends": "../../tsconfig.base.json"
}
Package override after:
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"noImplicitOverride": false
}
}
Use a per-package override like this only to defer a base flag temporarily when one package is not ready yet.
Workflow
- Capture the current config shape and the commands it affects.
- Normalize duplicated or conflicting settings across the
extends chain.
- Tighten flags in a deliberate order using the reference path below.
- Keep module, path, include, exclude, and emit settings aligned with the actual build setup.
- When a config change creates a burst of compiler errors, stop changing config further and switch to
skills/tsc-error-triage/SKILL.md to work the failures in root-cause order.
- Re-run typecheck, build, and targeted tests after each meaningful config change.
- Stop widening the config change once the next flag would mix strictness work with emit, module, or package-layout churn.
Guardrails
- Must not enable many strictness flags at once without first measuring the failure surface.
- Must not change emit, module, or resolution settings casually when the task is only about strictness.
- Should preserve existing build outputs unless the user asked for a packaging change.
- Should prefer explicit per-package overrides over hidden config drift.
- May defer especially noisy flags with a clear note when the repository is not ready yet.
- Should stop the config sweep when failures spread beyond one or two localized areas; at that point the work has become compiler triage, not hardening.
Flag interaction notes
strict is the umbrella switch; do not expect it to be a no-op if package configs were already overriding pieces of it.
noUncheckedIndexedAccess often exposes index-signature and collection usage at once, so land it separately from optional-property changes.
exactOptionalPropertyTypes tends to ripple through object defaults and partial-update helpers, so keep the diff small enough to explain the actual API impact.
noImplicitOverride usually stays local to inheritance hierarchies and is a good follow-up batch after the broader nullability work.
- If a stricter flag would require
module, moduleResolution, or outDir changes to stay buildable, pause and re-evaluate the root cause before widening the config patch.
When to stop widening
Stop broadening the config work when any of these happen:
- the next change would touch both strictness and package-layout concerns
- the remaining failures are spread across unrelated packages
- the config diff no longer fits the current diagnosis in one review pass
- the only remaining fixes are code changes, not config changes
Routing boundary
- Use this skill when the primary work is TypeScript configuration cleanup or strictness sequencing.
- Route to
project-references-migration (archived) when the main goal is incremental tsc -b project-references adoption across a layered workspace.
- Route to
tsc-error-triage once config changes have landed and the task becomes source-level compiler error remediation.
Validation
Run the repository's typecheck command after each config batch.
Run the build if tsconfig affects emit or declaration generation.
Confirm the final config still matches the intended runtime and package layout.
Use references/hardening-scenarios.md to keep strictness sequencing, stop thresholds, and do-not-widen cases aligned with the maintenance loop.
Smoke test:
- should trigger: "Enable noImplicitAny and clean up this repo's tsconfig chain safely."
- should not trigger: "Fix the source errors from the last typecheck run." (→
tsc-error-triage)
Examples
- "Turn on stricter TypeScript settings without breaking the whole repo at once."
- "Clean up this messy
tsconfig hierarchy and make module resolution predictable."
- "Help me enable
noUncheckedIndexedAccess and exactOptionalPropertyTypes safely."
Reference files
references/strictness-path.md - a safe order for tightening common TypeScript compiler settings and related checks.
references/hardening-scenarios.md - scenario checklist for sequencing strictness work without widening scope.
1---2name: tsconfig-hardening3description: "Tighten and rationalize TypeScript configuration safely, especially when enabling stricter compiler checks incrementally. Use when enabling strict flags, untangling a tsconfig chain, or fixing module-resolution or emit config drift."4license: GNU GPL v35metadata:6 source: https://skillmd.com/skills/matt-riley/tsconfig-hardening7 version: 1.3.2 # x-release-please-version8 category: typescript9 audience: general-coding-agent10 maturity: stable11 kind: task12---1314# Tsconfig hardening1516## Use this skill when1718- The user wants to enable stricter TypeScript settings safely.19- A repository has a confusing `tsconfig` chain that needs cleanup or consolidation.20- Module resolution, emit behavior, or workspace config drift is causing recurring TypeScript issues.21- The user wants to change TypeScript configuration even if that work may produce compiler errors that will need follow-on triage.2223## Do not use this skill when2425- The task is to fix one local type error without changing project configuration.26- The build problem is mainly in Babel, bundler, or runtime tooling with no meaningful `tsconfig` change.27- The repository intentionally uses a loose config and the user did not ask to harden it.28- The main task is now triaging the compiler errors caused by an earlier config change rather than changing config further.2930## Inputs to gather3132**Required before editing**3334- The active `tsconfig` files and their `extends` chain.35- The repository's typecheck, build, and test commands.36- The current strictness posture, such as `strict`, `noImplicitAny`, or `noUncheckedIndexedAccess`.37- Whether the project emits JavaScript, declarations, or typechecks only.3839**Helpful if present**4041- Baseline compiler error counts before changing flags.42- Whether the repository mixes ESM and CJS.43- Package-level overrides in a monorepo.4445## First move46471. Inventory the `tsconfig` chain and run `tsc --showConfig` or the nearest equivalent when available.482. Capture the current typecheck/build command and baseline compiler error count before changing flags.493. Separate configuration cleanup from code fixes so the diff explains itself.504. Pick one strictness or resolution problem to address first instead of flipping every flag at once.5152## Concrete config diffs5354Base config before:5556```json57{58 "compilerOptions": {59 "strict": false,60 "noImplicitAny": false61 }62}63```6465Base config after:6667```json68{69 "compilerOptions": {70 "strict": false,71 "noImplicitAny": true72 }73}74```7576Use a single-flag step like this before considering `strict: true`; the umbrella switch is only safe when the blast radius is already understood.7778Package override before:7980```json81{82 "extends": "../../tsconfig.base.json"83}84```8586Package override after:8788```json89{90 "extends": "../../tsconfig.base.json",91 "compilerOptions": {92 "noImplicitOverride": false93 }94}95```9697Use a per-package override like this only to defer a base flag temporarily when one package is not ready yet.9899## Workflow1001011. Capture the current config shape and the commands it affects.1022. Normalize duplicated or conflicting settings across the `extends` chain.1033. Tighten flags in a deliberate order using the reference path below.1044. Keep module, path, include, exclude, and emit settings aligned with the actual build setup.1055. When a config change creates a burst of compiler errors, stop changing config further and switch to `skills/tsc-error-triage/SKILL.md` to work the failures in root-cause order.1066. Re-run typecheck, build, and targeted tests after each meaningful config change.1077. Stop widening the config change once the next flag would mix strictness work with emit, module, or package-layout churn.108109## Guardrails110111- **Must not** enable many strictness flags at once without first measuring the failure surface.112- **Must not** change emit, module, or resolution settings casually when the task is only about strictness.113- **Should** preserve existing build outputs unless the user asked for a packaging change.114- **Should** prefer explicit per-package overrides over hidden config drift.115- **May** defer especially noisy flags with a clear note when the repository is not ready yet.116- **Should** stop the config sweep when failures spread beyond one or two localized areas; at that point the work has become compiler triage, not hardening.117118## Flag interaction notes119120- `strict` is the umbrella switch; do not expect it to be a no-op if package configs were already overriding pieces of it.121- `noUncheckedIndexedAccess` often exposes index-signature and collection usage at once, so land it separately from optional-property changes.122- `exactOptionalPropertyTypes` tends to ripple through object defaults and partial-update helpers, so keep the diff small enough to explain the actual API impact.123- `noImplicitOverride` usually stays local to inheritance hierarchies and is a good follow-up batch after the broader nullability work.124- If a stricter flag would require `module`, `moduleResolution`, or `outDir` changes to stay buildable, pause and re-evaluate the root cause before widening the config patch.125126## When to stop widening127128Stop broadening the config work when any of these happen:129130- the next change would touch both strictness and package-layout concerns131- the remaining failures are spread across unrelated packages132- the config diff no longer fits the current diagnosis in one review pass133- the only remaining fixes are code changes, not config changes134135## Routing boundary136137- Use this skill when the primary work is TypeScript configuration cleanup or strictness sequencing.138- Route to [`project-references-migration`](../archived/project-references-migration/SKILL.md) (archived) when the main goal is incremental `tsc -b` project-references adoption across a layered workspace.139- Route to [`tsc-error-triage`](../tsc-error-triage/SKILL.md) once config changes have landed and the task becomes source-level compiler error remediation.140141## Validation142143- Run the repository's typecheck command after each config batch.144- Run the build if `tsconfig` affects emit or declaration generation.145- Confirm the final config still matches the intended runtime and package layout.146- Use [`references/hardening-scenarios.md`](references/hardening-scenarios.md) to keep strictness sequencing, stop thresholds, and do-not-widen cases aligned with the maintenance loop.147148- Smoke test:149 - should trigger: "Enable noImplicitAny and clean up this repo's tsconfig chain safely."150 - should not trigger: "Fix the source errors from the last typecheck run." (→ `tsc-error-triage`)151152## Examples153154- "Turn on stricter TypeScript settings without breaking the whole repo at once."155- "Clean up this messy `tsconfig` hierarchy and make module resolution predictable."156- "Help me enable `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` safely."157158## Reference files159160- [`references/strictness-path.md`](references/strictness-path.md) - a safe order for tightening common TypeScript compiler settings and related checks.161- [`references/hardening-scenarios.md`](references/hardening-scenarios.md) - scenario checklist for sequencing strictness work without widening scope.