TypeScript: Require the typecheck run for type checking in CI

.github/workflows/static-checks.yml

@@ -114,13 +114,16 @@ jobs:
                   npm run lint:css -- --formatter compact
                   npm run lint:css:update-suppressions
 
-            - name: Type check dev projects
-              # TODO: Fold the build type check below into this run once
-              # every package is migrated to the split tsconfig layout.
+            - name: Type checking
               run: npm run typecheck
 
-            - name: Type checking
-              run: npm run build
+            - name: Check type declaration files
+              # Runs against the declarations the type check just emitted;
+              # the bundle build below skips types and with them this check.
+              run: npm run check:type-declarations
+
+            - name: Build packages
+              run: npm run build -- --skip-types
 
             - name: Validate package contents
               run: npm run lint:package-contents

AGENTS.md

@@ -42,7 +42,7 @@ Read only what your task needs, when it needs it:
 ```bash
 npm run format            # Fix JS formatting
 npm run lint:js          # Check JS linting
-npm run typecheck        # Type check sources, plus dev files of migrated packages
+npm run typecheck        # Type check sources, plus TypeScript tests and stories
 vendor/bin/phpcbf        # Fix PHP standards
 vendor/bin/phpcs         # Check PHP standards
 
@@ -72,7 +72,7 @@ For full architecture details, see `docs/explanations/architecture/`.
 -   Never invoke WordPress's forked or local CLIs through `npx` (e.g. `npx prettier`, `npx wp-scripts`). WordPress ships its own `wp-prettier` fork, and `wp-scripts` is the bin name of `@wordpress/scripts`. A bare `npx wp-scripts` can resolve to an unrelated third-party package on the public registry, not the local tool. Use the npm scripts instead (`npm run format`, `npm run lint:js`, `npm run lint:css` and so on), which run the binaries from local `node_modules`.
 -   PHP function and class names are renamed at build time (`gutenberg_*` prefix, `*_Gutenberg` suffix) to avoid conflicts with WordPress Core — the built names, not the source names, are what runs (and what tests must call). See `docs/contributors/code/build-system-function-prefixing.md`.
 -   Production code changes in a package require an entry in that package's `CHANGELOG.md`. See `docs/contributors/code/managing-packages.md`.
--   TypeScript configs are being split per package, one package at a time: `tsconfig.build.json` (src only, emits `build-types`) and the default `tsconfig.json` (dev project: tests and stories, `noEmit`, jest types). References to a split package point at `../<pkg>/tsconfig.build.json`, references to a package still on a single config point at `../<pkg>`. `npm run build` does not type check the dev files of split packages; use `npm run typecheck` for those, and keep jest types out of build projects. See the TypeScript section in `packages/README.md`.
+-   Packages with TypeScript dev files split their configs: `tsconfig.build.json` (src only, emits `build-types`) and the default `tsconfig.json` (dev project: tests and stories, `noEmit`, jest types). Packages without dev files keep a single `tsconfig.json` build project. Reference a split package by `../<pkg>/tsconfig.build.json` and an unsplit one by `../<pkg>`. `npm run build` never type checks dev files; use `npm run typecheck` for that, and never add jest types to a build project. See the TypeScript section in `packages/README.md`.
 -   A rejected `apiFetch` is not always an `Error`: a REST error arrives as a plain object (`{ code, message, data }`), `parse: false` rejects with the `Response` (which carries `status`, not `message`), an aborted request rethrows an `AbortError`, and a handler set via `setFetchHandler` can reject anything. Do not interpolate the rejection into a string (`` `${ error }` `` gives `[object Object]`) or branch on `instanceof Error`. Normalise it to a message before showing the user anything, and supply your own copy when there is none — `ensureError` in `packages/core-data/src/private-actions.js` is the reference implementation, though it is local to that file rather than exported.
 
 ## PR instructions

package.json

@@ -97,6 +97,7 @@
 		"agents:setup": "npm run --workspace @wordpress/agent-tools setup --",
 		"build": "npm run --workspace @wordpress/build-scripts build:all --",
 		"build:plugin-zip": "bash ./bin/build-plugin-zip.sh",
+		"check:type-declarations": "npm run --workspace @wordpress/build-scripts check-type-declarations --",
 		"clean:package-types": "npm run --workspace @wordpress/build-scripts clean:package-types --",
 		"clean:packages": "npm run --workspace @wordpress/build-scripts clean:packages --",
 		"dev": "npm run --workspace @wordpress/build-scripts dev --",
@@ -185,7 +186,7 @@
 		"test:unit:update": "npm run --workspace @wordpress/unit-tests test:unit -- --updateSnapshot",
 		"test:unit:watch": "npm run --workspace @wordpress/unit-tests test:unit:watch --",
 		"pretypecheck": "npm run --workspace @wordpress/build-scripts generate-worker-placeholders --",
-		"typecheck": "tsc --build",
+		"typecheck": "npm run --workspace @wordpress/build-scripts typecheck --",
 		"wp-env": "wp-env",
 		"wp-env-test": "wp-env --config .wp-env.test.json"
 	},

packages/README.md

@@ -327,9 +327,7 @@ Gutenberg uses TypeScript for several reasons, including:
 Gutenberg uses TypeScript by running the TypeScript compiler (`tsc`) on select packages.
 These packages benefit from type checking and produced type declarations in the published packages.
 
-A package opts in to TypeScript tooling with a `tsconfig.json` in its root, registered in the root `tsconfig.build.json` references.
-
-Packages are being migrated to a two project layout, one package at a time:
+A package opts in to TypeScript tooling with a build project registered in the root `tsconfig.build.json` references: `tsconfig.json` for a package without TypeScript dev files, `tsconfig.build.json` for one that splits. Packages with TypeScript test or story files split into two projects:
 
 -   `tsconfig.build.json` is the build project: it covers `src`, emits declarations to `build-types`, and is what other packages and `npm run build` consume.
 -   `tsconfig.json` is the dev project: it covers test and story files with `noEmit`, so `npm run typecheck` and the IDE can check them without their declarations ending up in the published package.
@@ -343,8 +341,8 @@ Both extend shared base configurations (comments are not necessary):
 	"extends": "../../tsconfig.base.json",
 
 	// Dependencies that have opted in to TypeScript are referenced here: a
-	// migrated one by its build project, one still on a single config by
-	// its directory.
+	// split one by its build project, one on a single config by its
+	// directory.
 	"references": [
 		{ "path": "../dom-ready/tsconfig.build.json" },
 		{ "path": "../hooks" }
@@ -364,7 +362,7 @@ Both extend shared base configurations (comments are not necessary):
 }
 ```
 
-A migrated package registers both projects at the root: `packages/<name>/tsconfig.build.json` in the root `tsconfig.build.json` references, and `packages/<name>` in the root `tsconfig.json` references.
+Register both projects at the root: `packages/<name>/tsconfig.build.json` in the root `tsconfig.build.json` references, and `packages/<name>` in the root `tsconfig.json` references.
 
 Packages whose components feed the Storybook components manifest (`components`, `dataviews`, `ui`) carry a third project, `tsconfig.stories.json`, registered in the root `tsconfig.json` only. It type checks the stories against component sources without jest types. Storybook's component meta extractor reads props through the closest `tsconfig.json` that lists a story, or through its own inferred project when none does; the inferred project produces the complete manifest and the dev project does not, so stories stay out of `tsconfig.json`. The dev project cannot reference this one either, because a referenced project may not disable emit (TS6310), which is why it is registered at the root only.
 

packages/admin-ui/CHANGELOG.md

@@ -12,7 +12,7 @@
 
 ### Internal
 
--   Point tsconfig references at split dependencies' build projects. ([#81515](https://github.com/WordPress/gutenberg/pull/81515))
+-   Point tsconfig references at split dependencies' build projects. ([#81515](https://github.com/WordPress/gutenberg/pull/81515), [#81518](https://github.com/WordPress/gutenberg/pull/81518))
 -   Split tsconfig into a build project and a default dev project so dev files are type checked without publishing their declarations. ([#81514](https://github.com/WordPress/gutenberg/pull/81514))
 
 ## 2.8.0 (2026-08-12)

packages/admin-ui/tsconfig.build.json

@@ -10,7 +10,7 @@
 		{ "path": "../i18n/tsconfig.build.json" },
 		{ "path": "../private-apis" },
 		{ "path": "../route" },
-		{ "path": "../style-runtime" },
+		{ "path": "../style-runtime/tsconfig.build.json" },
 		{ "path": "../ui/tsconfig.build.json" }
 	]
 }

packages/admin-ui/tsconfig.json

@@ -12,7 +12,7 @@
 		{ "path": "../i18n/tsconfig.build.json" },
 		{ "path": "../private-apis" },
 		{ "path": "../route" },
-		{ "path": "../style-runtime" },
+		{ "path": "../style-runtime/tsconfig.build.json" },
 		{ "path": "../ui/tsconfig.build.json" }
 	]
 }

packages/block-editor/tsconfig.build.json

@@ -25,7 +25,7 @@
 		{ "path": "../icons/tsconfig.build.json" },
 		{ "path": "../image-cropper/tsconfig.build.json" },
 		{ "path": "../interactivity/tsconfig.build.json" },
-		{ "path": "../is-shallow-equal" },
+		{ "path": "../is-shallow-equal/tsconfig.build.json" },
 		{ "path": "../kebab-case" },
 		{ "path": "../keycodes/tsconfig.build.json" },
 		{ "path": "../keyboard-shortcuts" },

packages/block-editor/tsconfig.json

@@ -29,7 +29,7 @@
 		{ "path": "../icons/tsconfig.build.json" },
 		{ "path": "../image-cropper/tsconfig.build.json" },
 		{ "path": "../interactivity/tsconfig.build.json" },
-		{ "path": "../is-shallow-equal" },
+		{ "path": "../is-shallow-equal/tsconfig.build.json" },
 		{ "path": "../kebab-case" },
 		{ "path": "../keycodes/tsconfig.build.json" },
 		{ "path": "../keyboard-shortcuts" },

packages/blocks/tsconfig.json

@@ -15,7 +15,7 @@
 		{ "path": "../hooks" },
 		{ "path": "../html-entities/tsconfig.build.json" },
 		{ "path": "../i18n/tsconfig.build.json" },
-		{ "path": "../is-shallow-equal" },
+		{ "path": "../is-shallow-equal/tsconfig.build.json" },
 		{ "path": "../keycodes/tsconfig.build.json" },
 		{ "path": "../private-apis" },
 		{ "path": "../rich-text" },

packages/components/CHANGELOG.md

@@ -25,7 +25,7 @@
 
 ### Internal
 
--   Point tsconfig references at split dependencies' build projects. ([#81514](https://github.com/WordPress/gutenberg/pull/81514), [#81516](https://github.com/WordPress/gutenberg/pull/81516))
+-   Point tsconfig references at split dependencies' build projects. ([#81514](https://github.com/WordPress/gutenberg/pull/81514), [#81516](https://github.com/WordPress/gutenberg/pull/81516), [#81518](https://github.com/WordPress/gutenberg/pull/81518))
 -   Split tsconfig into a build project and a default dev project so dev files are type checked without publishing their declarations. ([#81515](https://github.com/WordPress/gutenberg/pull/81515))
 -   Remove `ValidatedComboboxControl` from the private APIs; it now lives internally in `@wordpress/dataviews`, its only consumer ([#81449](https://github.com/WordPress/gutenberg/pull/81449)).
 -   Remove `ValidatedFormTokenField` from the private APIs; it now lives internally in `@wordpress/dataviews`, its only consumer ([#81451](https://github.com/WordPress/gutenberg/pull/81451)).

packages/components/tsconfig.build.json

@@ -20,14 +20,14 @@
 		{ "path": "../html-entities/tsconfig.build.json" },
 		{ "path": "../i18n/tsconfig.build.json" },
 		{ "path": "../icons/tsconfig.build.json" },
-		{ "path": "../is-shallow-equal" },
+		{ "path": "../is-shallow-equal/tsconfig.build.json" },
 		{ "path": "../kebab-case" },
 		{ "path": "../keycodes/tsconfig.build.json" },
 		{ "path": "../primitives" },
 		{ "path": "../private-apis" },
 		{ "path": "../react-i18n" },
 		{ "path": "../rich-text" },
-		{ "path": "../style-runtime" },
+		{ "path": "../style-runtime/tsconfig.build.json" },
 		{ "path": "../ui/tsconfig.build.json" },
 		{ "path": "../warning" }
 	]

packages/components/tsconfig.json

@@ -32,14 +32,14 @@
 		{ "path": "../html-entities/tsconfig.build.json" },
 		{ "path": "../i18n/tsconfig.build.json" },
 		{ "path": "../icons/tsconfig.build.json" },
-		{ "path": "../is-shallow-equal" },
+		{ "path": "../is-shallow-equal/tsconfig.build.json" },
 		{ "path": "../kebab-case" },
 		{ "path": "../keycodes/tsconfig.build.json" },
 		{ "path": "../primitives" },
 		{ "path": "../private-apis" },
 		{ "path": "../react-i18n" },
 		{ "path": "../rich-text" },
-		{ "path": "../style-runtime" },
+		{ "path": "../style-runtime/tsconfig.build.json" },
 		{ "path": "../ui/tsconfig.build.json" },
 		{ "path": "../warning" }
 	]

packages/components/tsconfig.stories.json

@@ -36,14 +36,14 @@
 		{ "path": "../html-entities/tsconfig.build.json" },
 		{ "path": "../i18n/tsconfig.build.json" },
 		{ "path": "../icons/tsconfig.build.json" },
-		{ "path": "../is-shallow-equal" },
+		{ "path": "../is-shallow-equal/tsconfig.build.json" },
 		{ "path": "../kebab-case" },
 		{ "path": "../keycodes/tsconfig.build.json" },
 		{ "path": "../primitives" },
 		{ "path": "../private-apis" },
 		{ "path": "../react-i18n" },
 		{ "path": "../rich-text" },
-		{ "path": "../style-runtime" },
+		{ "path": "../style-runtime/tsconfig.build.json" },
 		{ "path": "../ui/tsconfig.build.json" },
 		{ "path": "../warning" }
 	]

packages/compose/tsconfig.build.json

@@ -8,7 +8,7 @@
 		{ "path": "../deprecated/tsconfig.build.json" },
 		{ "path": "../dom" },
 		{ "path": "../element/tsconfig.build.json" },
-		{ "path": "../is-shallow-equal" },
+		{ "path": "../is-shallow-equal/tsconfig.build.json" },
 		{ "path": "../keycodes/tsconfig.build.json" },
 		{ "path": "../priority-queue/tsconfig.build.json" },
 		{ "path": "../private-apis" },

packages/compose/tsconfig.json

@@ -9,7 +9,7 @@
 		{ "path": "../deprecated/tsconfig.build.json" },
 		{ "path": "../dom" },
 		{ "path": "../element/tsconfig.build.json" },
-		{ "path": "../is-shallow-equal" },
+		{ "path": "../is-shallow-equal/tsconfig.build.json" },
 		{ "path": "../keycodes/tsconfig.build.json" },
 		{ "path": "../priority-queue/tsconfig.build.json" },
 		{ "path": "../private-apis" },

packages/core-data/tsconfig.build.json

@@ -19,7 +19,7 @@
 		{ "path": "../html-entities/tsconfig.build.json" },
 		{ "path": "../i18n/tsconfig.build.json" },
 		{ "path": "../icons/tsconfig.build.json" },
-		{ "path": "../is-shallow-equal" },
+		{ "path": "../is-shallow-equal/tsconfig.build.json" },
 		{ "path": "../notices/tsconfig.build.json" },
 		{ "path": "../private-apis" },
 		{ "path": "../rich-text" },

packages/core-data/tsconfig.json

@@ -18,7 +18,7 @@
 		{ "path": "../html-entities/tsconfig.build.json" },
 		{ "path": "../i18n/tsconfig.build.json" },
 		{ "path": "../icons/tsconfig.build.json" },
-		{ "path": "../is-shallow-equal" },
+		{ "path": "../is-shallow-equal/tsconfig.build.json" },
 		{ "path": "../notices/tsconfig.build.json" },
 		{ "path": "../private-apis" },
 		{ "path": "../rich-text" },

packages/data/tsconfig.json

@@ -9,7 +9,7 @@
 		{ "path": "../deprecated/tsconfig.build.json" },
 		{ "path": "../element/tsconfig.build.json" },
 		{ "path": "../private-apis" },
-		{ "path": "../is-shallow-equal" },
+		{ "path": "../is-shallow-equal/tsconfig.build.json" },
 		{ "path": "../priority-queue/tsconfig.build.json" },
 		{ "path": "../redux-routine" }
 	]

packages/grid/CHANGELOG.md

@@ -4,7 +4,7 @@
 
 ### Internal
 
--   Point tsconfig references at split dependencies' build projects. ([#81514](https://github.com/WordPress/gutenberg/pull/81514))
+-   Point tsconfig references at split dependencies' build projects. ([#81514](https://github.com/WordPress/gutenberg/pull/81514), [#81518](https://github.com/WordPress/gutenberg/pull/81518))
 -   Split tsconfig into a build project and a default dev project; story and test declarations are no longer published to npm. ([#81509](https://github.com/WordPress/gutenberg/pull/81509))
 
 ## 0.5.0 (2026-08-12)

packages/grid/tsconfig.build.json

@@ -7,6 +7,6 @@
 	"references": [
 		{ "path": "../compose/tsconfig.build.json" },
 		{ "path": "../element/tsconfig.build.json" },
-		{ "path": "../style-runtime" }
+		{ "path": "../style-runtime/tsconfig.build.json" }
 	]
 }

packages/grid/tsconfig.json

@@ -9,6 +9,6 @@
 		{ "path": "./tsconfig.build.json" },
 		{ "path": "../compose/tsconfig.build.json" },
 		{ "path": "../element/tsconfig.build.json" },
-		{ "path": "../style-runtime" }
+		{ "path": "../style-runtime/tsconfig.build.json" }
 	]
 }

packages/is-shallow-equal/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Internal
+
+-   Split tsconfig into a build project and a default dev project so dev files are type checked without publishing their declarations. ([#81518](https://github.com/WordPress/gutenberg/pull/81518))
+
 ## 5.53.0 (2026-08-12)
 
 

packages/is-shallow-equal/package.json

@@ -45,6 +45,7 @@
 	"types": "build-types",
 	"sideEffects": false,
 	"devDependencies": {
+		"@types/jest": "^30.0.0",
 		"@wordpress/lazy-import": "file:../lazy-import",
 		"benchmark": "^2.1.4"
 	},

packages/is-shallow-equal/test/index.ts

@@ -146,7 +146,7 @@ describe( 'isShallowEqual', () => {
 	} );
 
 	it( 'returns true on arrays that are a copy of each other', () => {
-		const a = [];
+		const a: unknown[] = [];
 		const b = a;
 
 		expect( isShallowEqual( a, b ) ).toBe( true );

packages/is-shallow-equal/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig.json",
+	"extends": "../../tsconfig.base.json"
+}

packages/is-shallow-equal/tsconfig.json

@@ -1,4 +1,10 @@
 {
 	"$schema": "https://json.schemastore.org/tsconfig.json",
-	"extends": "../../tsconfig.base.json"
+	"extends": "../../tsconfig.dev.base.json",
+	// Tests live beside src, not under it.
+	"compilerOptions": {
+		"rootDir": "."
+	},
+	"include": [ "test/**/*.ts" ],
+	"references": [ { "path": "./tsconfig.build.json" } ]
 }

packages/plugins/tsconfig.json

@@ -11,6 +11,6 @@
 		{ "path": "../element/tsconfig.build.json" },
 		{ "path": "../hooks" },
 		{ "path": "../icons/tsconfig.build.json" },
-		{ "path": "../is-shallow-equal" }
+		{ "path": "../is-shallow-equal/tsconfig.build.json" }
 	]
 }

packages/style-runtime/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Internal
+
+-   Split tsconfig into a build project and a default dev project so dev files are type checked without publishing their declarations. ([#81518](https://github.com/WordPress/gutenberg/pull/81518))
+
 ## 0.9.0 (2026-08-12)
 
 

packages/style-runtime/global.d.ts

@@ -0,0 +1,5 @@
+/*
+ * With typeRoots set in tsconfig, global types outside those directories,
+ * like the jest-dom matchers, must be referenced explicitly.
+ */
+import '@testing-library/jest-dom';

packages/style-runtime/package.json

@@ -41,6 +41,10 @@
 	},
 	"types": "build-types",
 	"sideEffects": false,
+	"devDependencies": {
+		"@testing-library/jest-dom": "^6.9.1",
+		"@types/jest": "^30.0.0"
+	},
 	"publishConfig": {
 		"access": "public"
 	}

packages/style-runtime/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig.json",
+	"extends": "../../tsconfig.base.json"
+}

packages/style-runtime/tsconfig.json

@@ -1,4 +1,11 @@
 {
 	"$schema": "https://json.schemastore.org/tsconfig.json",
-	"extends": "../../tsconfig.base.json"
+	"extends": "../../tsconfig.dev.base.json",
+	// Tests live beside src, not under it.
+	"compilerOptions": {
+		"rootDir": "."
+	},
+	"files": [ "global.d.ts" ],
+	"include": [ "test/**/*.ts" ],
+	"references": [ { "path": "./tsconfig.build.json" } ]
 }

packages/theme/CHANGELOG.md

@@ -13,7 +13,7 @@
 
 ### Internal
 
--   Point tsconfig references at split dependencies' build projects. ([#81514](https://github.com/WordPress/gutenberg/pull/81514))
+-   Point tsconfig references at split dependencies' build projects. ([#81514](https://github.com/WordPress/gutenberg/pull/81514), [#81518](https://github.com/WordPress/gutenberg/pull/81518))
 -   Collapse the `tsconfig.src.json`/`tsconfig.bin.json`/`tsconfig.test.json` projects into the repository-standard split of `tsconfig.build.json` and a default dev `tsconfig.json`. ([#81509](https://github.com/WordPress/gutenberg/pull/81509))
 -   Update Terrazzo packages to 2.5.0, use its resolver for mode overrides, and restore token linting with semantic WCAG AA contrast checks ([#81082](https://github.com/WordPress/gutenberg/pull/81082)).