Skip to content

Developer tools: Simplify editor setup and add Zed settings #84143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ciampo merged 6 commits into from
Oct 7, 2026
Merged

Developer tools: Simplify editor setup and add Zed settings #84143

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
37f30b8
Developer tools: Share editor settings and add Zed support
ciampo Oct 7, 2026
f8acfa3
Docs: Clarify automatic editor settings setup
ciampo Oct 7, 2026
826595e
Developer tools: Simplify Zed setup with static settings
ciampo Oct 7, 2026
5574027
docs: Clarify Cursor TypeScript setup
ciampo Oct 7, 2026
8592eb3
Developer tools: Keep editor setup project-specific
ciampo Oct 7, 2026
30bd3f5
Developer tools: Make Zed settings opt-in
ciampo Oct 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Developer tools: Simplify Zed setup with static settings
  • Loading branch information
@ciampo
ciampo committed Oct 7, 2026
commit 826595ecd228535fed83799f9435d20982f6558e
1 change: 0 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,6 @@ phpunit.xml
phpunit-watcher.yml
.tool-versions
/.vscode/settings.json
/.zed/settings.json
test/storybook-playwright/test-results
test/storybook-playwright/specs/__snapshots__
test/storybook-playwright/specs/*-snapshots/**
Expand Down
141 changes: 141 additions & 0 deletions .zed/settings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
{
"languages": {
"JavaScript": {
"language_servers": [
"typescript-ls",
"eslint",
"!vtsls",
"!typescript-language-server",
"..."
],
"format_on_save": "on",
"code_actions_on_format": {
"source.fixAll.eslint": true
}
},
"JSX": {
"language_servers": [
"typescript-ls",
"eslint",
"!vtsls",
"!typescript-language-server",
"..."
],
"format_on_save": "on",
"code_actions_on_format": {
"source.fixAll.eslint": true
}
},
"TypeScript": {
"language_servers": [
"typescript-ls",
"eslint",
"!vtsls",
"!typescript-language-server",
"..."
],
"format_on_save": "on",
"code_actions_on_format": {
"source.fixAll.eslint": true
}
},
"TSX": {
"language_servers": [
"typescript-ls",
"eslint",
"!vtsls",
"!typescript-language-server",
"..."
],
"format_on_save": "on",
"code_actions_on_format": {
"source.fixAll.eslint": true
}
},
"CSS": {
"language_servers": [ "stylelint-lsp", "..." ],
"format_on_save": "on",
"formatter": [
{
"code_action": "source.fixAll.stylelint"
}
]
},
"SCSS": {
"language_servers": [ "stylelint-lsp", "..." ],
"format_on_save": "on",
"formatter": [
{
"code_action": "source.fixAll.stylelint"
}
]
},
"PHP": {
"language_servers": [
"intelephense",
"phpcs",
"!phpactor",
"!phptools",
"!phpantom",
"..."
],
"format_on_save": "on",
"formatter": [
{
"code_action": "source.fixAll.phpcs"
}
]
}
},
"lsp": {
"typescript-ls": {
"binary": {
"path": "node",
"arguments": [
"tools/build-scripts/node_modules/@typescript/native/bin/tsc",
"--lsp",
"--stdio"
]
}
},
"eslint": {
"settings": {
"workingDirectory": {
"mode": "location"
},
"bulkSuppression": {
"enable": true,
"location": "tools/eslint/suppressions.json",
"severity": "hint"
}
}
},
"stylelint-lsp": {
"settings": {
"stylelint": {
"validate": [ "css", "postcss", "scss" ]
}
}
},
"intelephense": {
"settings": {
"environment": {
"phpVersion": "7.4.0"
},
"files": {
"exclude": [
"**/.cache/**",
"**/.git/**",
"**/.history/**",
"**/build/**",
"**/build-module/**",
"**/build-types/**",
"**/build-style/**",
"**/node_modules/**",
"**/vendor/**"
]
}
}
}
}
}
13 changes: 0 additions & 13 deletions .zed/tasks.json
View file
Open in desktop

This file was deleted.

22 changes: 8 additions & 14 deletions docs/contributors/code/getting-started-with-code-contribution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,29 +210,23 @@ You can also test Storybook for the current `trunk` branch on GitHub Pages: [htt

## Developer tools

We recommend configuring your editor to automatically check for syntax and lint errors. The repository includes managed settings for Visual Studio Code, Cursor, and Zed. Running `npm install` or `npm ci` generates each editor's local settings from [the shared editor configuration](https://github.com/WordPress/gutenberg/blob/HEAD/tools/monorepo/scripts/editor-settings.mts) through the automatic `prepare` hook. This does not build Gutenberg. With install scripts enabled, no separate editor setup command is needed. Other editors can use the same root formatting and lint configuration files.
We recommend configuring your editor to automatically check for syntax and lint errors. This will help you save time as you develop by automatically fixing minor formatting issues. The repository includes settings for Visual Studio Code, Cursor, and Zed. Other editors can use the same root formatting and lint configuration files.

### Visual Studio Code

Visual Studio Code and Cursor use `.vscode/settings.json`. Install the [recommended extensions](https://github.com/WordPress/gutenberg/blob/HEAD/.vscode/extensions.json) and allow the automatic task that refreshes the managed settings when the folder opens. When the TypeScript 7 extension asks whether to use the TypeScript 7 tsdk this workspace configures, choose **Allow**; otherwise it keeps using its bundled version.
If you use Visual Studio Code or Cursor, the repository ships a managed workspace configuration so the editor uses the same linting, formatting, PHP, and TypeScript tooling as the Gutenberg repository. The first time you open the folder, VS Code prompts you to install the [recommended extensions](https://github.com/WordPress/gutenberg/blob/HEAD/.vscode/extensions.json) and to allow an automatic task that copies [`.vscode/settings.dist.jsonc`](https://github.com/WordPress/gutenberg/blob/HEAD/.vscode/settings.dist.jsonc) to `.vscode/settings.json`. Allow both. When the TypeScript 7 extension then asks whether to use the TypeScript 7 tsdk this workspace configures, choose **Allow**; otherwise it keeps using its bundled version.
Comment thread
ciampo marked this conversation as resolved.
Outdated

The installer replaces `settings.json` whenever its first line is `// This is a managed VS Code settings file.`, so edits made there are lost the next time the folder opens or the installer runs. To keep your own settings, delete that line; the installer then leaves the file alone. You can re-run it at any time from the Command Palette via **Tasks: Run Task → Install VS Code settings**.

The settings point the TypeScript, ESLint, Prettier, and Stylelint extensions at the workspaces that install them, because those tools are not installed in the root `node_modules`. If you maintain your own settings, copy those paths from the shared editor configuration.
The settings point the TypeScript extension at the workspace that installs TypeScript 7, because it is not installed in the root `node_modules`. If you maintain your own settings, copy `js/ts.tsdk.path` and `js/ts.experimental.useTsgo` from the template.

### Zed

Zed uses `.zed/settings.json`, which dependency installation generates for each checkout. Install the **TypeScript Language Server** (`tsgo`), **PHP** (`php`), **PHPCS** (`phpcs`), **Stylelint** (`stylelint`), and **SCSS & SASS** (`scss`) extensions through **zed: extensions** in the Command Palette. JavaScript, JSX, TypeScript, TSX, CSS, and ESLint support are built in. Zed reads `.editorconfig` without an extension.
Open the repository root in Zed after installing dependencies with `npm install` and `composer install`. The checked-in [`.zed/settings.json`](https://github.com/WordPress/gutenberg/blob/HEAD/.zed/settings.json) applies automatically. No settings generation or refresh task is needed.

The settings use the repository's native TypeScript language server, WordPress Prettier, ESLint, Stylelint, and Composer-installed PHPCS and PHPCBF. Run `composer install` before editing PHP. Intelephense uses the same PHP version and exclusions as Visual Studio Code. Saving JavaScript and TypeScript runs ESLint fixes and Prettier; saving CSS or SCSS runs Stylelint fixes; saving PHP runs PHPCS fixes.
Install **TypeScript Language Server** (`tsgo`), **PHP** (`php`), **PHPCS** (`phpcs`), **Stylelint** (`stylelint`), and **SCSS & SASS** (`scss`) through **zed: extensions** in the Command Palette. Zed includes ESLint support and reads `.editorconfig` without an extension. Make sure `node` and `php` are available on your `PATH`.

If you pulled editor configuration changes into an existing checkout without reinstalling dependencies, refresh Zed settings with **task: spawn → Install Zed settings**, or run:

```bash
npm run install-zed-settings --workspace @wordpress/monorepo-tools
```

The installer replaces `.zed/settings.json` while its first line is `// This is a managed Zed settings file.` Remove that line to preserve your custom settings. Managed Zed settings contain local absolute paths; refresh them after moving the checkout or changing the Node executable. If you installed dependencies with `--ignore-scripts`, run `npm run prepare` to install the managed editor settings and Git hooks.
The settings select the repository's native TypeScript language server and show suppressed ESLint violations as hints. Saving JavaScript or TypeScript runs ESLint fixes and WordPress Prettier. Saving CSS or SCSS runs Stylelint fixes; saving PHP runs PHPCS fixes. The integrations discover the root npm tools and Composer's `vendor/bin` executables automatically and use the repository's existing lint and formatting rules.

### EditorConfig

Expand All @@ -242,13 +236,13 @@ The installer replaces `.zed/settings.json` while its first line is `// This is

[ESLint](https://eslint.org/) statically analyzes the code to find problems. The lint rules are integrated in the continuous integration process and must pass to be able to commit. With an editor integration enabled, ESLint will use the [eslint.config.mjs](https://github.com/WordPress/gutenberg/blob/HEAD/eslint.config.mjs) file in the root of the Gutenberg repository to highlight issues as you develop.

If you use Visual Studio Code, Cursor, or Zed, use the setup instructions above. For other editors, see the [ESLint editor integration docs](https://eslint.org/docs/user-guide/integrations).
If you use Visual Studio Code, use the extension and settings listed in the [Visual Studio Code](#visual-studio-code) section above. For other editors, see the [ESLint editor integration docs](https://eslint.org/docs/user-guide/integrations).

### Prettier

[Prettier](https://prettier.io/) is a tool that allows you to define an opinionated format, and automate fixing the code to match that format. Prettier and ESLint are similar, Prettier is more about formatting and style, while ESLint is for detecting coding errors.

Editor integrations use the `prettier.config.mjs` file included in the root of the Gutenberg repository. The config is included from the [@wordpress/prettier-config](/packages/prettier-config/README.md) package. If you use Visual Studio Code, Cursor, or Zed, use the setup instructions above.
Editor integrations use the `prettier.config.mjs` file included in the root of the Gutenberg repository. The config is included from the [@wordpress/prettier-config](/packages/prettier-config/README.md) package. If you use Visual Studio Code, use the extension and settings listed in the [Visual Studio Code](#visual-studio-code) section above.

For other editors, see [Prettier's Editor Integration docs](https://prettier.io/docs/en/editors.html).

Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,7 @@
"other:generate-php-sync-issue": "npm run --workspace @wordpress/release-tools generate-php-sync-issue --",
"other:update-packages:php": "wp-env run --env-cwd='wp-content/plugins/gutenberg' cli composer update --no-interaction",
"postinstall": "npm run agents:setup -- --if-safe",
"prepare": "husky install && npm run install-editor-settings --workspace @wordpress/monorepo-tools",
"prepare": "husky install",
"prepublishOnly": "npm run build",
"rtc:http": "node ./test/e2e/bin/rtc-dev.mjs --mode=http",
"rtc:ws": "node ./test/e2e/bin/rtc-dev.mjs --mode=websockets",
Expand Down
8 changes: 2 additions & 6 deletions tools/monorepo/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,13 +29,9 @@ See the TypeScript section of [`packages/README.md`](../../packages/README.md) f

`npm run --workspace @wordpress/monorepo-tools list-experimental-apis` prints a Markdown list of every `__experimental` API in `packages/` and `lib/`, each linked to a GitHub search for it. Release leads run it to audit experimental APIs ahead of a major WordPress release, as in [the WordPress 6.2 audit](https://github.com/WordPress/gutenberg/issues/47196).

## Editor settings
## VS Code settings

`scripts/editor-settings.mts` holds shared tool paths, generated-file exclusions, PHP settings, and ESLint suppression settings, together with their VS Code and Zed translations. Formatting and lint rules remain in the root `.editorconfig`, `prettier.config.mjs`, `eslint.config.mjs`, `.stylelintrc.mjs`, and `phpcs.xml.dist` files.

`npm run --workspace @wordpress/monorepo-tools install-editor-settings` generates `.vscode/settings.json` and `.zed/settings.json`. Both `npm install` and `npm ci` run it automatically through the root `prepare` hook, without building Gutenberg. If you skip install scripts or pull editor configuration changes without reinstalling dependencies, run the installer directly. To refresh only one editor, use `install-vscode-settings` or `install-zed-settings`; both editors also have an **Install settings** task.

The installer replaces a settings file only while its first line is the managed comment for that editor. Remove that line to preserve customizations. Generated settings are ignored by Git. Zed settings contain local absolute paths so language servers and formatters use the installed workspace tools across platforms; re-run the installer after moving a checkout or changing the Node executable.
`npm run --workspace @wordpress/monorepo-tools install-vscode-settings` copies `.vscode/settings.dist.jsonc` to `.vscode/settings.json`, unless that file no longer starts with `// This is a managed VS Code settings file.` A VS Code task runs it when the folder opens.

## Admin design tokens experiment

Expand Down
4 changes: 1 addition & 3 deletions tools/monorepo/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,7 @@
"access": "public"
},
"scripts": {
"install-editor-settings": "node scripts/install-editor-settings.mts",
"install-vscode-settings": "node scripts/install-editor-settings.mts vscode",
"install-zed-settings": "node scripts/install-editor-settings.mts zed",
"install-vscode-settings": "node scripts/install-vscode-settings.mts",
"list-experimental-apis": "node scripts/list-experimental-apis.mts",
"wpds:admin-scheme-tokens": "node wpds/generate-admin-scheme-tokens.mjs"
}
Expand Down
Loading
Loading