NPM Package: Introduce @wordpress/ts-config

[im3dabasia]

What?

Closes: #48954

This PR introduces a new @wordpress/ts-config package, allowing Gutenberg and external WordPress packages, plugins, and themes to share a common TypeScript configuration.

Why?

Currently, Gutenberg's TypeScript configuration is defined in a central tsconfig.base.json, but it is loaded via relative paths across many @wordpress/* packages. This approach prevents external developers from reusing the configuration.

By introducing @wordpress/ts-config, we align TypeScript with other existing configuration packages (e.g., @wordpress/eslint-plugin, @wordpress/prettier-config) and improve maintainability.

How?

Created @wordpress/ts-config containing the tsconfig.base.json file.

1. Updated all @wordpress/* packages to extend TypeScript configuration via the new package instead of relative paths.
2. Updated the test/ folder to use the package in the e2e/ and performance/ folders.

{
  "extends": "@wordpress/ts-config/tsconfig.base.json"
}

Key Changes:

1. Updated typeRoots Paths

• Previously, typeRoots used ./typings and ./node_modules/@types, which only worked when the file was placed at the root level.
• Now, typeRoots uses ../../typings and ../../node_modules/@types to correctly reference the root from packages/ts-config.

2. Introduced ${configDir} for Path Resolution

• TypeScript 5.5 introduced the ${configDir} template variable, which ensures paths are resolved relative to the file that extends the config, rather than where the base config is located. Reference
• ${configDir} was already used for rootDir and declarationDir to handle paths relative to the extended configuration.
• This change also applies ${configDir} to exclude patterns because it is essential to ensure that paths are correctly resolved relative to the extending project, not the ts-config package itself. Without this, paths would be incorrectly interpreted based on the location of @wordpress/ts-config, causing unintended behavior.

Testing Instructions

1. Install Dependencies

First, ensure all dependencies are installed:

npm install

2. Navigate to the @wordpress/ts-config Package

Move into the package directory:

cd packages/ts-config

3. Link the Package

Run the following command to create a global symlink:

npm link

4. Link the Package in Gutenberg Root

Navigate back to the Gutenberg root directory:

cd ../../  # Go back to the root
npm link @wordpress/ts-config

5. Verify the Linking

Check if the package is linked correctly:

npm ls @wordpress/ts-config

Output:

[email protected] /Users/im3dabasia/Desktop/gutenberg
└── @wordpress/[email protected] -> ./packages/ts-config

6. Continue with build and development

npm run dev; 

[im3dabasia]

This is an effort to address this issue by introducing the new @wordpress/ts-config as highlighted in this issue #48954 package for centralized TypeScript configuration.

I would appreciate your review and any feedback you may have.

Thank you!

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @AdarshRawat1.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: AdarshRawat1.

Co-authored-by: im3dabasia <[email protected]>
Co-authored-by: gziolo <[email protected]>
Co-authored-by: swissspidy <[email protected]>
Co-authored-by: Chrico <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[swissspidy]

These are specific to the Gutenberg repository and should remain in the root tsconfig.base.json file, no?

It doesn't make sense for external developers.

[swissspidy]

Previously shared here too:

#48954 (comment)

[im3dabasia]

@swissspidy ,

Thank you for the feedback. I see your point about the excludes being quite specific to Gutenberg. That said, many of these exclusions—such as build folders, benchmarks, and test directories—are commonly needed across different projects, not just within packages/.

Would it be worth refining the exclude rules to make them more broadly applicable while still avoiding Gutenberg-specific paths? If we can generalize them without including packages/, we might be able to create a more reusable configuration. I'd be happy to explore this further if you think it would be valuable

[im3dabasia]

@swissspidy , I'd appreciate your thoughts on the points mentioned above. Would you be so kind as to share your perspective on whether they are worth exploring further?

[swissspidy]

Generalizing the list would help a little bit, but then you risk excluding too many things, and you would still need some Gutenberg-specific exclusions anyway.

In my view we should:

1. Undo the changes to the individual package's tsconfig.json files and keep "extends": "../../tsconfig.base.json", there.
2. Have /tsconfig.base.json do "extends": "@wordpress/ts-config/tsconfig.base.json", and keep defining include and exclude there
   • Aside: For some reason this PR didn't change /tsconfig.base.json yet, but that file will need to be modified either way
3. So basically @wordpress/ts-config/tsconfig.base.json would only define compilerOptions

But I don't know what other projects typically do for this and I certainly don't want to be a deciding factor here, so I'll let others chime in.

[im3dabasia]

Thank you, @swissspidy. As suggested, I'll wait for others to share their opinions on whether this change is needed.

cc: @WordPress/gutenberg-components