1# Developing Extensions
  2
  3## Extension Capabilities
  4
  5Extensions can add the following capabilities to Zed:
  6
  7- [Languages](./languages.md)
  8- [Themes](./themes.md)
  9- [Icon Themes](./icon-themes.md)
 10- [Slash Commands](./slash-commands.md)
 11- [Context Servers](./context-servers.md)
 12
 13## Developing an Extension Locally
 14
 15Before starting to develop an extension for Zed, be sure to [install Rust via rustup](https://www.rust-lang.org/tools/install).
 16
 17When developing an extension, you can use it in Zed without needing to publish it by installing it as a _dev extension_.
 18
 19From the extensions page, click the `Install Dev Extension` button and select the directory containing your extension.
 20
 21If you already have a published extension with the same name installed, your dev extension will override it.
 22
 23## Directory Structure of a Zed Extension
 24
 25A Zed extension is a Git repository that contains an `extension.toml`. This file must contain some
 26basic information about the extension:
 27
 28```toml
 29id = "my-extension"
 30name = "My extension"
 31version = "0.0.1"
 32schema_version = 1
 33authors = ["Your Name <you@example.com>"]
 34description = "My cool extension"
 35repository = "https://github.com/your-name/my-zed-extension"
 36```
 37
 38In addition to this, there are several other optional files and directories that can be used to add functionality to a Zed extension. An example directory structure of an extension that provides all capabilities is as follows:
 39
 40```
 41my-extension/
 42  extension.toml
 43  Cargo.toml
 44  src/
 45    lib.rs
 46  languages/
 47    my-language/
 48      config.toml
 49      highlights.scm
 50  themes/
 51    my-theme.json
 52```
 53
 54## WebAssembly
 55
 56Procedural parts of extensions are written in Rust and compiled to WebAssembly. To develop an extension that includes custom code, include a `Cargo.toml` like this:
 57
 58```toml
 59[package]
 60name = "my-extension"
 61version = "0.0.1"
 62edition = "2021"
 63
 64[lib]
 65crate-type = ["cdylib"]
 66
 67[dependencies]
 68zed_extension_api = "0.1.0"
 69```
 70
 71Make sure to use the latest version of the [`zed_extension_api`](https://crates.io/crates/zed_extension_api) available on crates.io.
 72
 73In the `src/lib.rs` file in your Rust crate you will need to define a struct for your extension and implement the `Extension` trait, as well as use the `register_extension!` macro to register your extension:
 74
 75```rs
 76use zed_extension_api as zed;
 77
 78struct MyExtension {
 79    // ... state
 80}
 81
 82impl zed::Extension for MyExtension {
 83    // ...
 84}
 85
 86zed::register_extension!(MyExtension);
 87```
 88
 89## Publishing your extension
 90
 91To publish an extension, open a PR to [the `zed-industries/extensions` repo](https://github.com/zed-industries/extensions).
 92
 93> Note: It is very helpful if you fork the `zed-industries/extensions` repo to a personal GitHub account instead of a GitHub organization, as this allows Zed staff to push any needed changes to your PR to expedite the publishing process.
 94
 95In your PR, do the following:
 96
 971. Add your extension as a Git submodule within the `extensions/` directory
 98
 99```sh
100git submodule add https://github.com/your-username/foobar-zed.git extensions/foobar
101git add extensions/foobar
102```
103
1042. Add a new entry to the top-level `extensions.toml` file containing your extension:
105
106```toml
107[my-extension]
108submodule = "extensions/my-extension"
109version = "0.0.1"
110```
111
1123. Run `pnpm sort-extensions` to ensure `extensions.toml` and `.gitmodules` are sorted
113
114Once your PR is merged, the extension will be packaged and published to the Zed extension registry.
115
116> Extension IDs and names should not contain `zed` or `Zed`, since they are all Zed extensions.
117
118## Updating an extension
119
120To update an extension, open a PR to [the `zed-industries/extensions` repo](https://github.com/zed-industries/extensions).
121
122In your PR do the following:
123
1241. Update the extension's submodule to the commit of the new version.
1252. Update the `version` field for the extension in `extensions.toml`
126   - Make sure the `version` matches the one set in `extension.toml` at the particular commit.
127
128If you'd like to automate this process, there is a [community GitHub Action](https://github.com/huacnlee/zed-extension-action) you can use.