Ensure refs in tsconfig files are synced with internal deps by mcmire · Pull Request #8384 · MetaMask/core

mcmire · 2026-04-06T15:39:44Z

Explanation

We use project references to tell TypeScript and other tools about the structure of the monorepo. Both the root- and package-level tsconfig files have a references field which is used to link packages together. All packages that we want to build and publish need to be present in references within the root tsconfig.json and tsconfig.build.json files, and the references field in both root-level and package-level tsconfig files need to list all internal dependencies.

However, it's a pain to keep references up to date, especially as as packages are added or dependencies are updated. There are cases in the past, in fact, where packages were not published or type errors occurred because the references were not correctly kept in sync.

We don't need to do this manual work. We can infer root references by scanning workspaces, and we can infer references for an individual package by scanning that package's dependencies for other workspace packages.

This commit adds a script that can be run on both the root workspace and child workspaces to check and/or regenerate the references field for each tsconfig file so that it is kept in sync with dependencies throughout the monorepo. There are also new package scripts for use:

Root level
- lint:tsconfigs: Validates the root tsconfig.json and tsconfig.build.json, erroring if any are out of sync.
- lint:tsconfigs:all: Validates all tsconfig.json and tsconfig.build.json across the monorepo, erroring if any are out of sync.
- lint:tsconfigs:fix: Regenerates the root tsconfig.json and tsconfig.build.json.
- lint:tsconfigs:fix:all: Regenerates tsconfig.json and tsconfig.build.json files across the monorepo.
Package level
- lint:tsconfigs: Validates tsconfig.json and tsconfig.build.json in the package, erroring if any are out of sync.
- lint:tsconfigs:fix: Regenerates tsconfig.json and tsconfig.build.json in the package.

As the names indicate, tsconfig file validation is also a part of the lint pipeline, so CI will now fail if any files are out of date. To make sure this doesn't happen in the future, this commit also corrects tsconfig files across the board to add missing references or remove extra references.

Finally, it's worth noting that there are some existing solutions for syncing references within the TypeScript community, some of which are documented in this issue. However, I reviewed them and rejected them for various reasons:

typescript-monorepo-toolkit: Doesn't update references for individual packages based on dependencies
update-ts-references: Works, but re-sorts all references, and drops the leading ./ from references in root tsconfig files; also, generated files fail Prettier validation
@monorepo-utils/workspaces-to-typescript-project-references: Works, but re-sorts all references, and drops the leading ./ from references in root tsconfig files; also generated files fail Prettier validation

My thought is that by building our own script, we get to control the exact changes that are made to tsconfig files, and we get to run all files through Prettier so that engineers do not have to reformat them manually.

References

Closes #966.

Checklist

I've updated the test suite for new or updated code as appropriate
I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
I've communicated my changes to consumers by updating changelogs for packages I've changed
I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

Note

Medium Risk
Medium risk because it touches build tooling/TypeScript project references across many packages, which can break CI builds or publishing if reference inference is wrong, though runtime code changes are minimal.

Overview
Adds a new scripts/lint-tsconfigs tool and wires it into the root lint pipeline and CI (lint:tsconfigs:all), with --fix variants to regenerate tsconfig references.

Updates many package tsconfig.json/tsconfig.build.json files to sync references with internal dependencies (including adding/removing specific refs), and adds per-package lint:tsconfigs scripts (plus tsx devDependency where needed) so workspaces can validate/fix locally.

Includes a few related cleanups: broadens ESLint’s node config to cover scripts/**/*.ts, tweaks README dependency graph entries, removes a network-controller type-compat test from eth-json-rpc-middleware, and adds explicit deps in a couple packages (e.g., @metamask/preferences-controller in eip-5792-middleware, @metamask/controller-utils in keyring-controller).

^{Reviewed by Cursor Bugbot for commit f6f4a91. Bugbot is set up for automated code reviews on this repo. Configure here.}

We use project references to tell TypeScript and other tools about the structure of the monorepo. Both the root- and package-level tsconfig files have a `references` field which is used to link packages together. All packages that we want to build and publish need to be present in `references` within the root `tsconfig.json` and `tsconfig.build.json` files, and the `references` field in both root-level and package-level tsconfig files need to list all internal dependencies. However, manually keeping all of these references up to date as packages are added or dependencies are updated is a pain. There are cases where packages were not published or type errors occurred because the references were not correctly kept in sync. We don't need to do this manual work. We can infer root references by scanning workspaces, and we can infer references for an individual package by scanning that package's `dependencies` for other workspace packages. This commit adds a script that can be run on both the root workspace and child workspaces to check and/or regenerate the `references` field for each tsconfig file so that it is perfectly kept in sync with dependencies throughout the monorepo. There are also some package scripts for use: - Root level - **`lint:tsconfigs`:** Validates the root `tsconfig.json` and `tsconfig.build.json`, erroring if any are out of sync. - **`lint:tsconfigs:all`:** Validates all `tsconfig.json` and `tsconfig.build.json` across the monorepo, erroring if any are out of sync. - **`lint:tsconfigs:fix`:** Regenerates the root `tsconfig.json` and `tsconfig.build.json`. - **`lint:tsconfigs:fix:all`:** Regenerates `tsconfig.json` and `tsconfig.build.json` files across the monorepo. - Package level - **`lint:tsconfigs`:** Validates `tsconfig.json` and `tsconfig.build.json` in the package, erroring if any are out of sync. - **`lint:tsconfigs:fix`:** Regenerates `tsconfig.json` and `tsconfig.build.json` in the package. As the names indicate, tsconfig file validation is also a part of the lint pipeline, so CI will now fail if any files are out of date. Finally, it's worth noting that there are some existing solutions in the TypeScript community, some of which are documented in [this issue][1], but all of which were rejected for various reasons: - **[`typescript-monorepo-toolkit`][2]:** Doesn't update references for individual packages based on `dependencies` - **[`update-ts-references`][3]:** Works, but re-sorts all references, and drops the leading `./` from references in root tsconfig files; also, generated files fail Prettier validation - **[`@monorepo-utils/workspaces-to-typescript-project-references`][4]:** Works, but re-sorts all references, and drops the leading `./` from references in root tsconfig files; also generated files fail Prettier validation Essentially, by building our own script, we get to control the exact changes that are made to tsconfig files, and we get to run all files through Prettier so that engineers do not have to reformat them manually. [1]: microsoft/TypeScript#25376 [2]: https://github.com/Bnaya/typescript-monorepo-toolkit [3]: https://github.com/eBayClassifiedsGroup/update-ts-references [4]: https://github.com/azu/monorepo-utils/tree/master/packages/@monorepo-utils/workspaces-to-typescript-project-references

…on-standard format

mcmire · 2026-04-06T15:43:31Z

packages/accounts-controller/tsconfig.build.json

+      "path": "../messenger/tsconfig.build.json"
+    },
+    {
+      "path": "../controller-utils/tsconfig.build.json"


This dependency is present in devDependencies but was missing as a reference.

mcmire · 2026-04-06T15:43:34Z

packages/accounts-controller/tsconfig.json

+      "path": "../messenger"
+    },
+    {
+      "path": "../controller-utils"


This dependency is present in devDependencies but was missing as a reference.

mcmire · 2026-04-06T15:44:42Z

packages/assets-controller/tsconfig.build.json

+      "path": "../preferences-controller/tsconfig.build.json"
+    },
+    {
+      "path": "../controller-utils/tsconfig.build.json"


All of these dependencies are present in dependencies but were missing as references.

mcmire · 2026-04-06T15:44:52Z

packages/assets-controller/tsconfig.json

+      "path": "../preferences-controller"
+    },
+    {
+      "path": "../controller-utils"


All of these dependencies are present in dependencies but were missing as references.

mcmire · 2026-04-06T15:45:27Z

packages/assets-controllers/tsconfig.build.json

+      "path": "../phishing-controller/tsconfig.build.json"
+    },
+    {
+      "path": "../multichain-account-service/tsconfig.build.json"


These dependencies are present in dependencies but were missing as references.

mcmire · 2026-04-06T16:08:43Z

packages/transaction-pay-controller/tsconfig.build.json

      "path": "../transaction-controller/tsconfig.build.json"
+    },
+    {
+      "path": "../messenger/tsconfig.build.json"


New dependency.

mcmire · 2026-04-06T16:09:02Z

packages/user-operation-controller/tsconfig.build.json

      "path": "../messenger/tsconfig.build.json"
+    },
+    {
+      "path": "../approval-controller/tsconfig.build.json"


New dependency.

mcmire · 2026-04-06T16:09:06Z

packages/user-operation-controller/tsconfig.build.json

+      "path": "../approval-controller/tsconfig.build.json"
+    },
+    {
+      "path": "../eth-block-tracker/tsconfig.build.json"


New dev dependency.

mcmire · 2026-04-06T16:18:02Z

tsconfig.json

      "path": "./packages/user-operation-controller"
+    },
+    {
+      "path": "./packages/eip-5792-middleware"


Not sure how these were never added to the root tsconfig 🤔

mcmire · 2026-04-06T16:18:56Z

eslint.config.mjs

      '**/tests/**/*.{js,ts}',
-      'scripts/*.ts',
-      'scripts/create-package/**/*.ts',
+      'scripts/**/*.ts',


We've added a new subdirectory to scripts so rather than adding an extra entry here we can consolidate them all into one glob.

…c-middleware

socket-security · 2026-04-06T17:52:12Z

No dependency changes detected. Learn more about Socket for GitHub.

👍 No dependency changes detected in pull request

mcmire · 2026-04-06T17:52:03Z

packages/keyring-controller/tsconfig.build.json

    },
    {
-      "path": "../messenger/tsconfig.build.json"
+      "path": "../controller-utils/tsconfig.build.json"


Not entirely a new dependency, but it should have been added before (see above).

mcmire · 2026-04-06T17:54:17Z

packages/keyring-controller/package.json

    "@ethereumjs/util": "^9.1.0",
    "@metamask/base-controller": "^9.0.1",
    "@metamask/browser-passworder": "^6.0.0",
+    "@metamask/controller-utils": "^11.20.0",


Adding this dependency was necessary to avoid a type error. This should have been added — and the type error should have been present — all along, but for some reason only popped up now. It's possible that with the new changes on this branch, keyring-controller was getting built before controller-utils; if so, this corrects it.

mcmire · 2026-04-06T17:56:41Z

packages/eth-json-rpc-middleware/package.json

  },
  "devDependencies": {
    "@metamask/auto-changelog": "^3.4.4",
-    "@metamask/network-controller": "^30.0.1",


It turns out that there has been a circular dependency between network-controller and eth-json-rpc-middleware ever since the latter package was moved from the eth-json-rpc-middleware repo, and the problem didn't pop up until now.

network-controller is used in a test to confirm that a type that eth-json-rpc-middleware copies from network-controller is compatible with the same type from network-controller itself. I wasn't sure that this was necessary because now that eth-json-rpc-middleware is in this monorepo, if there are any type incompatibilities between types, they should show up locally (and any breaking changes to types should be spotted during development or at least during review). So I opted to remove the test file and thus the dependency on network-controller.

mcmire · 2026-04-06T17:57:02Z

packages/eth-json-rpc-middleware/tsconfig.json

      "path": "../json-rpc-engine"
    },
-    {
-      "path": "../network-controller"


mcmire · 2026-04-06T17:59:27Z

@SocketSecurity ignore npm/@metamask/preferences-controller@23.1.0

This is our package.

mcmire · 2026-04-06T18:00:49Z

Adding no-changelog here because none of the changes to tsconfigs need to be logged.

mcmire · 2026-04-06T18:03:24Z

packages/eip-5792-middleware/package.json

  },
  "dependencies": {
    "@metamask/messenger": "^1.1.1",
+    "@metamask/preferences-controller": "^23.1.0",


Added to avoid a new type error. Similar to #8384 (comment).

mcmire · 2026-04-06T20:22:27Z

Curious if our team should be co-codeowners of tsconfig.json and tsconfig.build.json files 🤔 This would make this PR merge a lot faster.

cryptodev-2s · 2026-04-07T11:57:26Z

Curious if our team should be co-codeowners of tsconfig.json and tsconfig.build.json files 🤔 This would make this PR merge a lot faster.

I do believe we should

mcmire force-pushed the lint-tsconfig-files branch from 2929cc5 to 6cb4611 Compare April 6, 2026 15:41

mcmire added 4 commits April 6, 2026 09:55

When appending new references, preserve order even in the case of a n…

5a85c1c

…on-standard format

Normalise -> normalize

a0fe302

Remove old JSDoc

783f7e5

Minor tweaks

4e56c94

mcmire commented Apr 6, 2026

View reviewed changes

mcmire added 5 commits April 6, 2026 11:47

Fix eip-5792-middleware to add missing dependency

fa6349c

Remove circular dependency between network-controller and eth-json-rp…

563913f

…c-middleware

Fix keyring-controller to add missing dependency

464d1bc

Remove needless ts-expect-error

7d12bc9

Fix lint violation

56f2779

mcmire commented Apr 6, 2026

View reviewed changes

Correct changelog

03f4104

mcmire added the no-changelog label Apr 6, 2026

mcmire commented Apr 6, 2026

View reviewed changes

mcmire added 3 commits April 6, 2026 12:03

Update lockfile

6236cfc

Update README

5b487e7

Fix missing comma

f6f4a91

mcmire marked this pull request as ready for review April 6, 2026 19:54

mcmire requested review from a team as code owners April 6, 2026 19:54

Uh oh!

Conversation

mcmire commented Apr 6, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation

References

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

socket-security bot commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcmire Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcmire commented Apr 6, 2026

Uh oh!

mcmire commented Apr 6, 2026

Uh oh!

mcmire Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcmire commented Apr 6, 2026

Uh oh!

cryptodev-2s commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mcmire commented Apr 6, 2026 •

edited by cursor bot

Loading

socket-security bot commented Apr 6, 2026 •

edited

Loading

mcmire Apr 6, 2026 •

edited

Loading

mcmire Apr 6, 2026 •

edited

Loading