Document why baseUrl is omitted in tsconfig.json

[plx]

Summary

• Add an inline comment explaining that baseUrl is intentionally omitted: TypeScript 5.5+ permits paths without baseUrl under moduleResolution: "bundler" (inherited from astro/tsconfigs/strict), and path values resolve relative to the tsconfig itself.

Addresses PR feedback requesting documentation of why the baseUrl removal is safe, to avoid confusing readers who may copy this config into a TS 4.x project.

Test plan

• just build succeeds

[github-actions]

PR Validation ✅

All checks passed! Ready for review.

Checks Performed:

✓ Linting
✓ Spell check (source)
✓ Type checking & Build
✓ Spell check (HTML)
✓ Internal link validation
✓ Artifact upload

This is a complete dry-run of the deployment process, ensuring your changes will deploy successfully when merged.

[claude]

Code Review

Overview

This PR adds a 3-line comment to tsconfig.json documenting why baseUrl is intentionally absent, addressing a valid concern that readers copying this config into a TypeScript 4.x project could run into breakage.

What's Good

• Right problem to solve: an unexplained absence is more confusing than an explained one, and this is exactly the kind of "non-obvious WHY" that warrants a comment.
• Well-placed: the comment sits directly above the paths block it explains — easy for readers to find.
• Concise: explains the constraint, the mechanism, and the implication in three lines without padding.

One Concern — Version Number

The comment says "TypeScript 5.5+", but moduleResolution: "bundler" was introduced in TypeScript 5.0 (March 2023), and the ability to use paths without baseUrl under non-classic resolution modes has been supported since at least TypeScript 4.1. Stating 5.5 as the floor could mislead a reader into thinking the config is needlessly cutting-edge, or cause them to doubt it on a 5.0–5.4 project where it works fine.

Suggested alternatives:

// baseUrl is intentionally omitted: TypeScript 5.0+ permits `paths` without
// `baseUrl` under `moduleResolution: "bundler"` (set by astro/tsconfigs/strict).
// Path values resolve relative to this tsconfig.json.

Or, if the intent is specifically to warn TS 4.x users:

// baseUrl is intentionally omitted. Under moduleResolution: "bundler"
// (TypeScript 5.0+, set by astro/tsconfigs/strict), `paths` entries resolve
// relative to this file without requiring baseUrl. TS 4.x projects need baseUrl.

Everything Else

• No logic changes; no risk of regression.
• just build passing is the right signal for a config-only change.
• No test coverage needed beyond the build check.

Verdict

Approve with the minor version-number nit — worth a quick fix before merge so the comment doesn't mislead readers on TS 5.0–5.4.

[github-actions]

PR Validation ✅

All checks passed! Ready for review.

Checks Performed:

✓ Linting
✓ Spell check (source)
✓ Type checking & Build
✓ Spell check (HTML)
✓ Internal link validation
✓ Artifact upload

This is a complete dry-run of the deployment process, ensuring your changes will deploy successfully when merged.

[claude]

Code Review — PR #44: Document why baseUrl is omitted in tsconfig.json

Overview

A minimal, targeted documentation PR: adds a 2-line inline comment to tsconfig.json explaining that omitting baseUrl is intentional and safe under the inherited moduleResolution: "bundler" setting.

---

Code Quality & Correctness ✅

The comment is accurate. TypeScript 5.0+ (specifically with moduleResolution: "bundler") permits paths without baseUrl, and path values resolve relative to the tsconfig.json file itself. Astro's tsconfigs/strict preset sets this mode, so the explanation is self-consistent with the file's "extends" line.

Placement (directly above "paths") is logical — it's exactly where a reader would look when encountering the missing baseUrl.

---

Suggestions

Minor: Consider mentioning the TS version floor in the comment

The PR description notes "TypeScript 5.5+" but the comment in the file doesn't. The version detail is the most actionable piece of information for someone who might cargo-cult this config into an older project. A small addition like:

// baseUrl is intentionally omitted: TypeScript 5.0+ with `moduleResolution: "bundler"`
// (set by astro/tsconfigs/strict) allows `paths` to resolve relative to this tsconfig.json.

This is optional — the current comment is already clear and not misleading — but the version anchor would make the "safe to omit" claim more concrete.

---

Risks & Concerns

None. This is a comment-only change with no runtime impact. The just build check in the test plan is appropriate to confirm no regressions.

---

Summary

Approve. The change is correct, well-placed, and directly addresses the documentation gap flagged in prior review feedback. The minor suggestion above is optional polish, not a blocker.