Configuring supported languages

Zed offers powerful customization options for each programming language it supports. This guide will walk you through the various ways you can tailor your coding experience to your preferences and project requirements.

Zed's language support is built on two main technologies:

Tree-sitter: This handles syntax highlighting and structure-based features like the outline panel.
Language Server Protocol (LSP): This provides semantic features such as code completion and diagnostics.

These components work together to provide Zed's language capabilities.

In this guide, we'll cover:

Language-specific settings
File associations
Working with language servers
Formatting and linting configuration
Customizing syntax highlighting and themes
Advanced language features

By the end of this guide, you should know how to configure and customize supported languages in Zed.

For a comprehensive list of languages supported by Zed and their specific configurations, see our Supported Languages page. To go further, you could explore developing your own extensions to add support for additional languages or enhance existing functionality. For more information on creating language extensions, see our Language Extensions guide.

Language-specific Settings

Zed allows you to override global settings for individual languages. These custom configurations are defined in your settings.json file under the languages key.

Here's an example of language-specific settings:

"languages": {
  "Python": {
    "tab_size": 4,
    "formatter": "language_server",
    "format_on_save": true
  },
  "JavaScript": {
    "tab_size": 2,
    "formatter": {
      "external": {
        "command": "prettier",
        "arguments": ["--stdin-filepath", "{buffer_path}"]
      }
    }
  }
}

You can customize a wide range of settings for each language, including:

tab_size: The number of spaces for each indentation level
formatter: The tool used for code formatting
format_on_save: Whether to automatically format code when saving
enable_language_server: Toggle language server support
hard_tabs: Use tabs instead of spaces for indentation
preferred_line_length: The recommended maximum line length
soft_wrap: How to wrap long lines of code

These settings allow you to maintain specific coding styles across different languages and projects.

File Associations

Zed automatically detects file types based on their extensions, but you can customize these associations to fit your workflow.

To set up custom file associations, use the file_types setting in your settings.json:

"file_types": {
  "C++": ["c"],
  "TOML": ["MyLockFile"],
  "Dockerfile": ["Dockerfile*"]
}

This configuration tells Zed to:

Treat .c files as C++ instead of C
Recognize files named "MyLockFile" as TOML
Apply Dockerfile syntax to any file starting with "Dockerfile"

You can use glob patterns for more flexible matching, allowing you to handle complex naming conventions in your projects.

Working with Language Servers

Language servers are a crucial part of Zed's intelligent coding features, providing capabilities like auto-completion, go-to-definition, and real-time error checking.

What are Language Servers?

Language servers implement the Language Server Protocol (LSP), which standardizes communication between the editor and language-specific tools. This allows Zed to support advanced features for multiple programming languages without implementing each feature separately.

Some key features provided by language servers include:

Code completion
Error checking and diagnostics
Code navigation (go to definition, find references)
Code actions (Rename, extract method)
Hover information
Workspace symbol search

Managing Language Servers

Zed simplifies language server management for users:

Automatic Download: When you open a file with a matching file type, Zed automatically downloads the appropriate language server. Zed may prompt you to install an extension for known file types.
Storage Location:
- macOS: ~/Library/Application Support/Zed/languages
- Linux: $XDG_DATA_HOME/languages, $FLATPAK_XDG_DATA_HOME/languages, or $HOME/.local/share
Automatic Updates: Zed keeps your language servers up-to-date, ensuring you always have the latest features and improvements.

Choosing Language Servers

Some languages in Zed offer multiple language server options. You might have multiple extensions installed that bundle language servers targeting the same language, potentially leading to overlapping capabilities. To ensure you get the functionality you prefer, Zed allows you to prioritize which language servers are used and in what order.

You can specify your preference using the language_servers setting:

  "languages": {
    "PHP": {
      "language_servers": ["intelephense", "!phpactor", "..."]
    }
  }

In this example:

intelephense is set as the primary language server
phpactor is disabled (note the ! prefix)
... preserves any other default language server settings

This configuration allows you to tailor the language server setup to your specific needs, ensuring that you get the most suitable functionality for your development workflow.

Configuring Language Servers

Many language servers accept custom configuration options. You can set these in the lsp section of your settings.json:

  "lsp": {
    "rust-analyzer": {
      "initialization_options": {
        "checkOnSave": {
          "command": "clippy"
        }
      }
    }
  }

This example configures the Rust Analyzer to use Clippy for additional linting when saving files.

When configuring language server options in Zed, it's important to use nested objects rather than dot-delimited strings. This is particularly relevant when working with more complex configurations. Let's look at a real-world example using the TypeScript language server:

Suppose you want to configure the following settings for TypeScript:

Enable strict null checks
Set the target ECMAScript version to ES2020
Configure import organization preferences

Here's how you would structure these settings in Zed's settings.json:

Here's how you might incorrectly attempt to set these options using dot notation:

"lsp": {
  "typescript-language-server": {
    "initialization_options": {
      // This is not supported:
      //   "preferences.strictNullChecks": true,
      // You express it like this:
      "preferences": {
        "strictNullChecks": true
      }
    }
  }
}

Enabling or Disabling Language Servers

You can toggle language server support globally or per-language:

  "languages": {
    "Markdown": {
      "enable_language_server": false
    }
  }

This disables the language server for Markdown files, which can be useful for performance in large documentation projects. You can configure this globally in your ~/.zed/settings.json or inside a .zed/settings.json in your project directory.

Formatting and Linting

Zed provides support for code formatting and linting to maintain consistent code style and catch potential issues early.

Configuring Formatters

Zed supports both built-in and external formatters. Configure formatters globally or per-language in your settings.json:

"languages": {
  "JavaScript": {
    "formatter": {
      "external": {
        "command": "prettier",
        "arguments": ["--stdin-filepath", "{buffer_path}"]
      }
    },
    "format_on_save": true
  },
  "Rust": {
    "formatter": "language_server",
    "format_on_save": true
  }
}

This example uses Prettier for JavaScript and the language server's formatter for Rust, both set to format on save.

To disable formatting for a specific language:

"languages": {
  "Markdown": {
    "format_on_save": false
  }
}

Setting Up Linters

Linting in Zed is typically handled by language servers. Many language servers allow you to configure linting rules:

"lsp": {
  "eslint": {
    "settings": {
      "codeActionOnSave": {
        "rules": ["import/order"]
      }
    }
  }
}

This configuration sets up ESLint to organize imports on save for JavaScript files.

To run linter fixes automatically on save:

"languages": {
  "JavaScript": {
    "code_actions_on_format": {
      "source.fixAll.eslint": true
    }
  }
}

Integrating Formatting and Linting

Zed allows you to run both formatting and linting on save. Here's an example that uses Prettier for formatting and ESLint for linting JavaScript files:

"languages": {
  "JavaScript": {
    "formatter": {
      "external": {
        "command": "prettier",
        "arguments": ["--stdin-filepath", "{buffer_path}"]
      }
    },
    "code_actions_on_format": {
      "source.fixAll.eslint": true
    },
    "format_on_save": true
  }
}

Troubleshooting

If you encounter issues with formatting or linting:

Check Zed's log file for error messages (Use the command palette: zed: open log)
Ensure external tools (formatters, linters) are correctly installed and in your PATH
Verify configurations in both Zed settings and language-specific config files (e.g., .eslintrc, .prettierrc)

Syntax Highlighting and Themes

Zed offers customization options for syntax highlighting and themes, allowing you to tailor the visual appearance of your code.

Customizing Syntax Highlighting

Zed uses Tree-sitter grammars for syntax highlighting. Override the default highlighting using the experimental.theme_overrides setting:

"experimental.theme_overrides": {
  "syntax": {
    "comment": {
      "font_style": "italic"
    },
    "string": {
      "color": "#00AA00"
    }
  }
}

This example makes comments italic and changes the color of strings.

Language-Specific Theme Overrides

Apply theme overrides for specific languages:

"languages": {
  "Python": {
    "theme_overrides": {
      "syntax": {
        "function": {
          "color": "#0000FF"
        }
      }
    }
  }
}

This configuration changes the color of function names in Python files.

Selecting and Customizing Themes

Change your theme:

Use the theme selector (cmd-k cmd-t|ctrl-k ctrl-t)
Or set it in your settings.json:

"theme": {
  "mode": "dark",
  "dark": "One Dark",
  "light": "GitHub Light"
}

Create custom themes by creating a JSON file in ~/.config/zed/themes/. Zed will automatically detect and make available any themes in this directory.

Using Theme Extensions

Zed supports theme extensions. Browse and install theme extensions from the Extensions panel (cmd-shift-e|ctrl-shift-e).

To create your own theme extension, refer to the Developing Theme Extensions guide.

Using Language Server Features

Inlay Hints

Inlay hints provide additional information inline in your code, such as parameter names or inferred types. Configure inlay hints in your settings.json:

"inlay_hints": {
  "enabled": true,
  "show_type_hints": true,
  "show_parameter_hints": true,
  "show_other_hints": true
}

For language-specific inlay hint settings, refer to the documentation for each language.

Code Actions

Code actions provide quick fixes and refactoring options. Access code actions using the editor: Toggle Code Actions command or by clicking the lightbulb icon that appears next to your cursor when actions are available.

Go To Definition and References

Use these commands to navigate your codebase:

editor: Go to Definition (f12|f12)
editor: Go to Type Definition (cmd-f12|ctrl-f12)
editor: Find All References (shift-f12|shift-f12)

Rename Symbol

To rename a symbol across your project:

Place your cursor on the symbol
Use the editor: Rename Symbol command (f2|f2)
Enter the new name and press Enter

These features depend on the capabilities of the language server for each language.

When renaming a symbol that spans multiple files, Zed will open a preview in a multibuffer. This allows you to review all the changes across your project before applying them. To confirm the rename, simply save the multibuffer. If you decide not to proceed with the rename, you can undo the changes or close the multibuffer without saving.