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- [Slash Commands](./slash-commands.md)
10- [Context Servers](./context-servers.md)
11
12## Developing an Extension Locally
13
14Before starting to develop an extension for Zed, be sure to [install Rust via rustup](https://www.rust-lang.org/tools/install).
15
16When developing an extension, you can use it in Zed without needing to publish it by installing it as a _dev extension_.
17
18From the extensions page, click the `Install Dev Extension` button and select the directory containing your extension.
19
20If you already have a published extension with the same name installed, your dev extension will override it.
21
22## Directory Structure of a Zed Extension
23
24A Zed extension is a Git repository that contains an `extension.toml`. This file must contain some
25basic information about the extension:
26
27```toml
28id = "my-extension"
29name = "My extension"
30version = "0.0.1"
31schema_version = 1
32authors = ["Your Name <you@example.com>"]
33description = "My cool extension"
34repository = "https://github.com/your-name/my-zed-extension"
35```
36
37In 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:
38
39```
40my-extension/
41 extension.toml
42 Cargo.toml
43 src/
44 lib.rs
45 languages/
46 my-language/
47 config.toml
48 highlights.scm
49 themes/
50 my-theme.json
51```
52
53## WebAssembly
54
55Procedural 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:
56
57```toml
58[package]
59name = "my-extension"
60version = "0.0.1"
61edition = "2021"
62
63[lib]
64crate-type = ["cdylib"]
65
66[dependencies]
67zed_extension_api = "0.1.0"
68```
69
70Make sure to use the latest version of the [`zed_extension_api`](https://crates.io/crates/zed_extension_api) available on crates.io.
71
72In 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:
73
74```rs
75use zed_extension_api as zed;
76
77struct MyExtension {
78 // ... state
79}
80
81impl zed::Extension for MyExtension {
82 // ...
83}
84
85zed::register_extension!(MyExtension);
86```
87
88## Publishing your extension
89
90To publish an extension, open a PR to [the `zed-industries/extensions` repo](https://github.com/zed-industries/extensions).
91
92> 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.
93
94In your PR, do the following:
95
961. Add your extension as a Git submodule within the `extensions/` directory
972. Add a new entry to the top-level `extensions.toml` file containing your extension:
98
99```toml
100[my-extension]
101submodule = "extensions/my-extension"
102version = "0.0.1"
103```
104
1053. Run `pnpm sort-extensions` to ensure `extensions.toml` and `.gitmodules` are sorted
106
107Once your PR is merged, the extension will be packaged and published to the Zed extension registry.
108
109> Extension IDs and names should not contain `zed` or `Zed`, since they are all Zed extensions.
110
111## Updating an extension
112
113To update an extension, open a PR to [the `zed-industries/extensions` repo](https://github.com/zed-industries/extensions).
114
115In your PR do the following:
116
1171. Update the extension's submodule to the commit of the new version.
1182. Update the `version` field for the extension in `extensions.toml`
119 - Make sure the `version` matches the one set in `extension.toml` at the particular commit.
120
121If you'd like to automate this process, there is a [community GitHub Action](https://github.com/huacnlee/zed-extension-action) you can use.