VS Code: Add managed workspace config

[manzoorwanijk]

What?

Follow up to #83847, alternative to #84017. Restores the initial version of #77913, inspired by #77177 (comment)

Adds a managed VS Code workspace config to the repo:

• .vscode/extensions.json: recommended extensions (EditorConfig, PHP Intelephense, ESLint, Prettier, PHPCS, Stylelint).
• .vscode/settings.dist.jsonc: workspace settings template (formatters, code actions on save, Intelephense / PHPCS exclusions, js/ts.experimental.useTsgo, and the TypeScript, ESLint, Prettier and Stylelint paths).
• .vscode/tasks.json: folderOpen task that installs the template into .vscode/settings.json if a contributor doesn't already have a customised one.
• tools/monorepo/scripts/install-vscode-settings.mts: the cross-platform installer script.
• .gitignore: adds /.vscode/settings.json so the locally-installed copy isn't committed.

The installer is idempotent: it only writes when the existing settings.json matches a previous managed copy (detected by the // This is a managed VS Code settings file. header), so contributor customisations are never overwritten.

Why?

Since #83847, Prettier, ESLint and Stylelint are no longer installed in the root node_modules, so editor extensions fall back to their bundled versions unless pointed at the workspaces that declare them. Native TypeScript also needs js/ts.experimental.useTsgo and js/ts.tsdk.path, which no root dependency can provide (see #84017 (comment)). A managed settings template makes the supported VS Code experience reproducible without adding those dependencies back to the root.

The installer is a small TypeScript script run by Node's type stripping (no dependencies beyond Node built-ins) so it works on Windows, macOS, and Linux without a POSIX shell.

How?

• The folderOpen task runs npm run install-vscode-settings --workspace @wordpress/monorepo-tools, which executes tools/monorepo/scripts/install-vscode-settings.mts. VS Code prompts the contributor on first open before running the task.
• Task type is shell (not process) because on Windows npm is a .cmd shim and process would fail to resolve it.
• The installer aborts if the template is missing, no-ops if settings.json already matches it, aborts if settings.json lacks the managed header, and otherwise copies the template.
• The docs describe the managed setup instead of a copyable settings snippet.

Note: @typescript/native in root is already useless and it doesn't serve any purpose. I will remove it in a follow up PR.

Testing Instructions

1. Delete any existing .vscode/settings.json.
2. Open the repo in VS Code. When VS Code asks whether to allow automatic tasks, allow them.
3. Confirm .vscode/settings.json is created and matches .vscode/settings.dist.jsonc.
4. Re-open the folder. Confirm the task reports "Managed settings are up to date; no changes needed."
5. Remove the first line of .vscode/settings.json, run Tasks: Run Task → Install VS Code settings, and confirm it reports "Custom settings file; aborting."
6. Run "Format Document" on a JS file and confirm parenSpacing is applied.

Testing Instructions for Keyboard

N/A, no UI changes.

Screenshots or screencast

N/A, editor tooling only.

Use of AI Tools

Drafted with assistance from Claude Code. All changes were reviewed and tested locally before being pushed.

[github-actions]

🤖 PR meta 🤖

🎉 Props

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

Co-authored-by: manzoorwanijk <manzoorwanijk@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: jsnajdr <jsnajdr@git.wordpress.org>

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

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

📦 Bundle size

Size Change: 0 B

Total Size: 8.29 MB

_{9bbfac2 Run}

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric	4742352	trunk	% Change
timeToFirstByte	60.25 ms +7.88% -2.07%	54.35 ms +10.12% -3.59%	10.86%
largestContentfulPaint	98 ms +6.12% -2.04%	96 ms +2.08% -8.33%	2.08%
lcpMinusTtfb	37 ms +10.14% -3.11%	33.5 ms +28.96% -5.67%	10.45%
wpBeforeTemplate	29.01 ms +8.76% -0.62%	26.56 ms +12.84% -1.39%	9.22%
wpTemplate	26.64 ms +4.5% -2.1%	23.57 ms +3.31% -4.12%	13.03%
wpTotal	56.03 ms +8.46% -2.36%	50.4 ms +10.71% -3.12%	11.17%
wpMemoryUsage	7.65 MB +0% -0%	7.59 MB +0% -0%	0.73%
wpDbQueries	17 +0% -0%	17 +0% -0%	0%

front-end-classic-theme

Metric	4742352	trunk	% Change
timeToFirstByte	48.8 ms +6.76% -0.72%	44 ms +7.61% -0.8%	10.91%
largestContentfulPaint	108 ms +1.85% -1.85%	100 ms +2% -4%	8%
lcpMinusTtfb	58.2 ms +1.8% -1.8%	55.25 ms +1.72% -4.34%	5.34%
wpBeforeTemplate	25.37 ms +1.73% -1.14%	23.51 ms +3.32% -1.62%	7.91%
wpTemplate	20.4 ms +3.68% -2.7%	17.63 ms +6.69% -2.16%	15.71%
wpTotal	45.6 ms +6.51% -1.23%	40.96 ms +7.84% -0.9%	11.33%
wpMemoryUsage	6.27 MB +0% -0%	6.21 MB +0% -0%	1.04%
wpDbQueries	14 +0% -0%	14 +0% -0%	0%

media-processing

Metric	4742352	trunk	% Change
mediaProcessingJpeg	419.86 ms +2.24% -1.12%	411.23 ms +0.48% -1.18%	2.1%
mediaProcessingAvif	6209.61 ms +0.32% -0.04%	6190.1 ms +0.28% -0.16%	0.32%
mediaProcessingJpegToAvif	4350.17 ms +0.19% -0.29%	4304.87 ms +0.16% -0.19%	1.05%

media-upload

Metric	4742352	trunk	% Change
jpegUploadProcessing	1448.68 ms +36.46% -2.55%	1402.53 ms +0.25% -0.73%	3.29%
pngUploadProcessing	225.91 ms +2.88% -2.38%	199.32 ms +2.32% -13.66%	13.34%
largeJpegUploadProcessing	1428.75 ms +1.17% -1.13%	1410.94 ms +0.5% -0.94%	1.26%
multipleImageUploadProcessing	1538.69 ms +2.3% -0.8%	1542.41 ms +12.93% -0.87%	-0.24%

post-editor

Metric	4742352	trunk	% Change
serverResponse	535.21 ms +2.89% -8.13%	508.39 ms +9.16% -0.8%	5.28%
firstPaint	237.27 ms +29.61% -4.72%	252.91 ms +26.65% -8.16%	-6.18%
domContentLoaded	1186.04 ms +1.51% -1.45%	1200.8 ms +2.24% -3.39%	-1.23%
loaded	1187.62 ms +1.5% -1.45%	1202.26 ms +2.24% -3.4%	-1.22%
firstContentfulPaint	487.62 ms +2.57% -5.03%	499.3 ms +3.8% -3.02%	-2.34%
firstBlock	3570.08 ms +1.19% -0.86%	3542.49 ms +1.61% -1.13%	0.78%
type	21.52 ms +4.83% -6.51%	20.25 ms +9.28% -4.15%	6.27%
typeWithoutInspector	20.91 ms +3.63% -6.55%	21.04 ms +6.37% -3.14%	-0.62%
typeWithTopToolbar	27.92 ms +7.49% -3.12%	27.62 ms +3.4% -9.23%	1.09%
typeContainer	10.03 ms +4.39% -3.29%	8.96 ms +19.08% -1.9%	11.94%
focus	136.26 ms +1.82% -2.33%	86.38 ms +5.13% -6.36%	57.74%
firstFocus	255.11 ms +0% -0%	241.72 ms +0% -0%	5.54%
selectAll	563.95 ms +3.81% -0.17%	575.87 ms +5.13% -0.26%	-2.07%
listViewOpen	92.38 ms +4.58% -2.98%	70.86 ms +8.19% -7.04%	30.37%
inserterOpen	43.91 ms +12.98% -4.33%	26.93 ms +5.24% -7.8%	63.05%
inserterHover	13.43 ms +14% -7%	2.97 ms +7.07% -18.18%	352.19%
inserterSearch	9.51 ms +6.94% -3.15%	9.58 ms +7.52% -7.62%	-0.73%
loadPatterns	684.33 ms +4.69% -2.01%	736.98 ms +5.1% -5.17%	-7.14%
wpTotal	525.05 ms +2.95% -8.37%	498.08 ms +9.33% -0.84%	5.41%
wpMemoryUsage	13.20 MB +0% -0%	13.14 MB +0% -0%	0.47%
wpDbQueries	54 +0% -1.85%	54 +0% -1.85%	0%

site-editor

Metric	4742352	trunk	% Change
serverResponse	323.12 ms +2.14% -6.96%	318.74 ms +0.65% -10.04%	1.37%
firstPaint	196.5 ms +6.57% -7.27%	201.91 ms +21.77% -7.85%	-2.68%
domContentLoaded	920.57 ms +1.32% -1.21%	876.53 ms +2.48% -1.87%	5.02%
loaded	921.6 ms +1.32% -1.2%	877.56 ms +2.49% -1.88%	5.02%
firstContentfulPaint	372.36 ms +1.62% -1.25%	356.37 ms +2.79% -4.99%	4.49%
firstBlock	3407.3 ms +2.2% -1.33%	3117.03 ms +0.76% -1.07%	9.31%
type	16.17 ms +4.82% -1.67%	15.39 ms +3.44% -2.08%	5.07%
navigate	96.33 ms +10.96% -3.44%	110.53 ms +4.6% -4.02%	-12.85%
loadPatterns	1061.77 ms +11.63% -9.66%	1039.26 ms +2.79% -4.6%	2.17%
loadPages	1065.39 ms +3.4% -4.76%	1032.28 ms +1.63% -1.95%	3.21%
wpTotal	314.79 ms +2.1% -7.15%	310.23 ms +0.66% -10.32%	1.47%
wpMemoryUsage	12.25 MB +0% -0%	12.19 MB +0% -0%	0.47%
wpDbQueries	43 +2.33% -0%	44 +0% -2.27%	-2.27%

_{9bbfac2 Run}

🏁 Flaky tests

Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

pushes earlier threads above the canvas to keep the selected one aligned in /test/e2e/specs/editor/various/block-notes-floating.spec.js, passed after 1 failed attempt.

Error: expect(locator).toBeVisible() failed

Locator: getByRole('region', { name: /^(Notes|Editor settings)$/ }).getByRole('treeitem', { name: 'Note: Four: Comprehensive considerations regarding extraordinarily sophisticated implementation characteristics notwithstanding.' })
Expected: visible
Timeout: 5000ms
Error: element(s) not found

Call log:
  - Expect "toBeVisible" getByRole('region', { name: /^(Notes|Editor settings)$/ }).getByRole('treeitem', { name: 'Note: Four: Comprehensive considerations regarding extraordinarily sophisticated implementation characteristics notwithstanding.' }) with timeout 5000ms
  - waiting for getByRole('region', { name: /^(Notes|Editor settings)$/ }).getByRole('treeitem', { name: 'Note: Four: Comprehensive considerations regarding extraordinarily sophisticated implementation characteristics notwithstanding.' })

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/block-notes-floating.spec.js:551:4

should update the URL from the last navigation if only varies in the URL fragment in /test/e2e/specs/interactivity/router-navigate.spec.ts, passed after 1 failed attempt.

Error: expect(locator).toHaveText(expected) failed

Locator:  getByTestId('title')
Expected: "Link 1"
Received: "Main"
Timeout:  5000ms

Call log:
  - Expect "toHaveText" getByTestId('title') with timeout 5000ms
  - waiting for getByTestId('title')
    14 × locator resolved to <h2 data-testid="title">Main</h2>
       - unexpected value "Main"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/interactivity/router-navigate.spec.ts:160:25

_{9bbfac2 Run}

[ciampo]

Playing devil's advocate, but is there a reason why we wouldn't add the same configuration for other well-known IDEs such as Cursor, Zed, Jetbrain IDEs, and even ChatGPT / Claude / etc embedded IDEs?

[manzoorwanijk]

Playing devil's advocate, but is there a reason why we wouldn't add the same configuration for other well-known IDEs such as Cursor, Zed, Jetbrain IDEs, and even ChatGPT / Claude / etc embedded IDEs?

If anyone uses those IDE, they are welcome to add those configurations. I don’t use any of those and thus I have no idea how to set those up.

[jsnajdr]

Why does the Gutenberg config have opinions about formatOrSave or source.fixAll? This looks like a personal preference of a particular user, not something specific to the project.

[jsnajdr]

why we wouldn't add the same configuration for other well-known IDEs

Yes, that's the "can of worms" risk described in the original PR, but let's see if it's a real problem. Do you use any of these IDEs and is there some local config that you would like to have built-in?

The proposed VSCode config does two kinds of settings:

• mandatory, to make the common plugins work at all. These are the custom paths to Prettier, TypeScript and ESLint
• optional, like the list of recommended extensions you might want to use

Are there other IDEs that have built-in linting/typechecking/formatting support that is not going to work unless properly configured?

[ciampo]

why we wouldn't add the same configuration for other well-known IDEs

Yes, that's the "can of worms" risk described in the original PR, but let's see if it's a real problem. Do you use any of these IDEs and is there some local config that you would like to have built-in?

The proposed VSCode config does two kinds of settings:

• mandatory, to make the common plugins work at all. These are the custom paths to Prettier, TypeScript and ESLint
• optional, like the list of recommended extensions you might want to use

Are there other IDEs that have built-in linting/typechecking/formatting support that is not going to work unless properly configured?

Yes, I used Cursor extensively and I'm now testing out Zed. I guess once this PR is merged, I can look into how these IDEs are affected by the changes and, if needed, open PRs to add equivalent functionality (keeping it as minimum as possible)

[ciampo]

Why does the Gutenberg config have opinions about formatOrSave or source.fixAll? This looks like a personal preference of a particular user, not something specific to the project.

On my local settings, my CSS/SCSS override disables format-on-save because saving otherwise applies unwanted formatting on my machine.

I would keep the repository tool paths and formatter selection, and treat whether fixes run on save as an optional workflow choice.

[manzoorwanijk]

Why does the Gutenberg config have opinions about formatOrSave or source.fixAll? This looks like a personal preference of a particular user, not something specific to the project.

One can easily override it after removing the comment at the top.

On my local settings, my CSS/SCSS override disables format-on-save because saving otherwise applies unwanted formatting on my machine.

That smells like a conflict between your global user settings and what you have for this repo. These settings should fix that.

[jsnajdr]

One can easily override it after removing the comment at the top.

That doesn't answer the question why we have the settings at all 🙂 By the way, which "comment at the top" are we talking about? Even the settings file vaguely mentions some comments:

If you no longer want the settings managed, remove these comments.

But it's not clear what does it mean.

Yes, I used Cursor extensively and I'm now testing out Zed. I guess once this PR is merged, I can look into how these IDEs are affected by the changes and, if needed, open PRs to add equivalent functionality

I'm curious whether Zed will require the same kind of custom config to make TS/ESLint/Prettier work.

Now when even the root @typescript/native dep was removed, we are kind of forced to merge this PR. Another VSCode feature is now broken and needs a custom config.

[manzoorwanijk]

We could rethink #84017 and add not just prettier, but for ESLint, Stylelint and TypeScript. But, for TypeScript, nothing will work because the tools will expect node_modules/typescript to be there, which we can't do becuase of the way we need both TS v6 and V7.

So, we still need to configure TypeScript for VS Code, which makes this PR the only option. Then the ESLint and Prettier is just a couple of more lines in that config.

[jsnajdr]

But, for TypeScript, nothing will work because the tools will expect node_modules/typescript to be there, which we can't do becuase of the way we need both TS v6 and V7.

Until now, the solution was (or at least how I solved it locally) to enable the "Use TsGo" option of the VSCode TypeScript extension (the native preview version). Then the IDE uses the TS server from @typescript/native, but the rest of the tooling chain uses the v6 from typescript.

[manzoorwanijk]

Then the IDE uses the TS server from @typescript/native

I don't think that can be correct because @typescript/native is not the official name of any package; it's just our own alias for TS v7.

[jsnajdr]

I don't think that can be correct because @typescript/native is not the official name of any package; it's just our own alias for TS v7.

You're right, what really happens (probably, I didn't check it thoroughly) is that the TS extension uses a bundled version of native TS 7.0. That's good enough, we are not sensitive to a particular version.

[ciampo]

That smells like a conflict between your global user settings and what you have for this repo. These settings should fix that.

Exactly. All I wanted to say is that those config options look good to me, since it's exactly what I have on my local machine already.

[ciampo]

LGTM 🚀