Skip to content

chore: upgrade to TypeScript 7, replace ESLint/Prettier with Oxc - #2184

Merged
koistya merged 1 commit into
mainfrom
chore/ts7-oxc
Sep 12, 2026
Merged

koistya merged 1 commit into
mainfrom
chore/ts7-oxc

Conversation

@koistya

@koistya koistya commented Sep 12, 2026 •

Copy link
Copy Markdown
Member

TypeScript 7 ships no compatible programmatic API — the typescript package's main export is now a version stub. That is what makes this one change rather than two: typescript-eslint reads that API, so ESLint does not start on this repository at all (ts-api-utils throws on ts.TypeFlags.Intrinsic). The lint toolchain had to move with the compiler.

Before After
Compiler TypeScript 6 TypeScript 7 (native), apps/web excepted
Lint ESLint + typescript-eslint + @eslint-react Oxlint
Format Prettier Oxfmt
Internal imports @/ tsconfig alias Node # subpath imports

Cold tsc --build, measured at this migration: 6.5–8s → 1.5–2.5s.

The Astro exception

astro check also loads the removed API, and it is the only thing that type-checks .astro templates. apps/web therefore pins typescript to an npm alias of @typescript/typescript6 — the technique Microsoft recommends for tools still on the old API.

The split is narrow on purpose: apps/web/worker.ts is still compiled by TypeScript 7 from the root build, and apps/web has no typecheck script of its own, so no file is checked by two compilers writing the same .tsbuildinfo. Removed once Astro supports the 7.1 API (withastro/roadmap#1321).

Import convention

packages/ui already used # subpath imports; apps/app and apps/web now do too. The shared preset also no longer maps @/* into apps/web for every workspace — a footgun where a missed alias resolved into the marketing site.

apps/app declares #* in both package.json and tsconfig paths. That looks redundant and is not:

  • Rolldown probes .ts/.tsx on an imports target, but ignores array fallbacks.
  • TypeScript never probes, but honours array fallbacks.

Neither accepts the other's form. A conditional imports map keyed on the types condition satisfies both — tested, works — but its types branch must enumerate every extension and barrel shape the app uses, so it needs editing whenever the layout grows. Two one-line mappings do not. ADR-006 records the experiment so nobody re-derives it.

"#/*" is not an option: Node accepts it, Bun does not resolve it at all.

Lint and format policy

Oxlint runs the correctness category, plus a few rules named individually where the repository has a stated reason to want them. This is a deliberately narrower policy than the ESLint stack, not a port of it — a starter kit owes downstream projects a predictable baseline they can widen. ADR-005 names what that drops rather than implying parity. .astro is the weak spot: astro check types it, Oxlint sees only frontmatter, the Astro extension formats it in the editor, and no repository command touches its markup.

Oxfmt preserves the formatting contract the repository already had, so the switch carries no formatting diff. lint-staged stays, for its semantics rather than its speed: Git commits the index, so a hook reading the working tree would pass a partially staged file on edits that are not being committed.

Dependencies

Bumped throughout, including Vitest 5. Two majors held back deliberately:

  • Jotai 3 changes lazy atom initialization and fails theme.test.tsx — the behaviour apps/app/AGENTS.md documents as load-bearing for the no-flash theme.
  • Mermaid 12 switches the default layout engine to ELK and the default theme, restyling every diagram in the docs.

Fixes along the way

  • packageManager and engines.bun had been dropped by dependency churn. Not cosmetic: setup-bun resolves its version from those fields, so both workflows had silently started floating to whatever Bun is current.
  • The MCP lint tool discarded the diagnostics it existed to report (execa rejects on non-zero exit; Oxlint exits non-zero exactly when a file has problems), and interpolated a model-supplied filename straight into the command line, so --fix was an option rather than a path.
  • A ref written during render in useAuthForm; a Hono .on() handler whose mixed return union no longer picks an overload; a tsBuildInfoFile shared by apps/app and apps/web.

Verification

format:check, lint, infra:check, typecheck, astro check, tests (92 passed), build (4 workspaces), docs:build, install --frozen-lockfile — all pass. Also by hand: both wrangler dry-runs, both dev servers, and the pre-commit hook in staged and unstaged directions.

Syncing a project built on this starter kit

Downstream forks pull this in with the merge-seed skill, which encodes the rule that upstream owns mechanism while the fork owns identity and scope:

git remote add seed https://github.com/kriasoft/react-starter-kit.git
git fetch seed

Then run the merge-seed skill — /merge-seed, or just ask your agent to merge the seed. Expect conflicts concentrated in the manifests — adopt upstream's versions and scripts, keep project-only dependencies, then take upstream's lockfile and regenerate with bun install. eslint.config.ts and .prettierignore are deletions; a fork that customised either should port the intent into .oxlintrc.json / .oxfmtrc.json rather than keeping the file. The # convention is not mandatory downstream, but the diff deletes the @/* entries from apps/web/tsconfig.json and the shared preset — a fork still importing through @/ should keep its own paths entries rather than take those hunks.

Decisions

  • ADR-004 — TypeScript 7 everywhere, except astro check
  • ADR-005 — Oxlint and Oxfmt replace ESLint and Prettier
  • ADR-006 — internal imports use the # convention

@koistya
koistya force-pushed the chore/ts7-oxc branch 2 times, most recently from 4a721b8 to 9d24d32 Compare September 12, 2026 12:00
TypeScript 7 is the native compiler and ships no compatible programmatic API,
which forces the lint toolchain to move with it: `typescript-eslint` reads that
API, so ESLint does not start on this repository at all. Oxlint and Oxfmt
replace it. Internal imports move from the `@/` tsconfig alias to Node `#`
subpath imports, matching what `packages/ui` already did, and dependencies are
bumped.

`apps/web` pins `typescript` to an npm alias of `@typescript/typescript6`,
because `astro check` loads the removed API and is the only thing that type-
checks `.astro` templates. The pin is scoped to that workspace; the root build
still compiles its `worker.ts` with TypeScript 7.

Oxfmt reproduces Prettier's output byte for byte here, so the switch carries no
formatting diff. `lint-staged` stays: Git commits the index, so a hook reading
the working tree would pass a partially staged file on edits that are not being
committed. Oxlint runs `correctness` plus five named rules - a deliberately
narrower policy than the ESLint stack, documented as such.

Jotai 3 and Mermaid 12 are held back. Jotai 3 changes lazy atom initialization
and fails the theme test; Mermaid 12 switches the default layout engine and
theme, restyling every docs diagram. Both deserve their own change.

Fixes the new tooling surfaced: a ref written during render in `useAuthForm`,
a Hono `.on()` handler whose mixed return union no longer picks an overload, a
`tsBuildInfoFile` shared by `apps/app` and `apps/web`, `packageManager` and
`engines.bun` dropped by dependency churn (which had silently floated CI's Bun
to latest), and an MCP lint tool that threw away the diagnostics it existed to
report and accepted a model-supplied filename as an option.

Adds ADR-004 (TypeScript 7), ADR-005 (Oxlint/Oxfmt) and ADR-006 (subpath
imports).
@koistya
koistya merged commit e3d28ae into main Sep 12, 2026
7 checks passed
@koistya
koistya deleted the chore/ts7-oxc branch September 12, 2026 12:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant