Repository navigation
chore: upgrade to TypeScript 7, replace ESLint/Prettier with Oxc - #2184
Merged
Merged
Conversation
koistya
force-pushed
the
chore/ts7-oxc
branch
2 times, most recently
from
September 12, 2026 12:00
4a721b8 to
9d24d32
Compare
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
force-pushed
the
chore/ts7-oxc
branch
from
September 12, 2026 12:37
9d24d32 to
e2aea5e
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TypeScript 7 ships no compatible programmatic API — the
typescriptpackage's main export is now a version stub. That is what makes this one change rather than two:typescript-eslintreads that API, so ESLint does not start on this repository at all (ts-api-utilsthrows onts.TypeFlags.Intrinsic). The lint toolchain had to move with the compiler.apps/webexcepted@/tsconfig alias#subpath importsCold
tsc --build, measured at this migration: 6.5–8s → 1.5–2.5s.The Astro exception
astro checkalso loads the removed API, and it is the only thing that type-checks.astrotemplates.apps/webtherefore pinstypescriptto 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.tsis still compiled by TypeScript 7 from the root build, andapps/webhas notypecheckscript 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/uialready used#subpath imports;apps/appandapps/webnow do too. The shared preset also no longer maps@/*intoapps/webfor every workspace — a footgun where a missed alias resolved into the marketing site.apps/appdeclares#*in bothpackage.jsonand tsconfigpaths. That looks redundant and is not:.ts/.tsxon animportstarget, but ignores array fallbacks.Neither accepts the other's form. A conditional
importsmap keyed on thetypescondition satisfies both — tested, works — but itstypesbranch 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
correctnesscategory, 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..astrois the weak spot:astro checktypes 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-stagedstays, 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:
theme.test.tsx— the behaviourapps/app/AGENTS.mddocuments as load-bearing for the no-flash theme.Fixes along the way
packageManagerandengines.bunhad been dropped by dependency churn. Not cosmetic:setup-bunresolves its version from those fields, so both workflows had silently started floating to whatever Bun is current.--fixwas an option rather than a path.useAuthForm; a Hono.on()handler whose mixed return union no longer picks an overload; atsBuildInfoFileshared byapps/appandapps/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-seedskill, which encodes the rule that upstream owns mechanism while the fork owns identity and scope:Then run the
merge-seedskill —/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 withbun install.eslint.config.tsand.prettierignoreare deletions; a fork that customised either should port the intent into.oxlintrc.json/.oxfmtrc.jsonrather than keeping the file. The#convention is not mandatory downstream, but the diff deletes the@/*entries fromapps/web/tsconfig.jsonand the shared preset — a fork still importing through@/should keep its ownpathsentries rather than take those hunks.Decisions
astro check#convention