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
 10## Directory Structure of a Zed Extension
 11
 12A Zed extension is a Git repository that contains an `extension.toml`. This file must contain some
 13basic information about the extension:
 14
 15```toml
 16id = "my-extension"
 17name = "My extension"
 18version = "0.0.1"
 19schema_version = 1
 20authors = ["Your Name <you@example.com>"]
 21description = "My cool extension"
 22repository = "https://github.com/your-name/my-zed-extension"
 23```
 24
 25<!--
 26TBD: Document `slash_commands`, `indexed_docs_providers` (see: extensions/gleam/extension.toml)
 27-->
 28
 29In 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:
 30
 31```
 32my-extension/
 33  extension.toml
 34  Cargo.toml
 35  src/
 36    lib.rs
 37  languages/
 38    config.toml
 39    highlights.scm
 40  themes/
 41    my-theme.json
 42```
 43
 44## WebAssembly
 45
 46Procedural 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:
 47
 48```toml
 49[package]
 50name = "my-extension"
 51version = "0.0.1"
 52edition = "2021"
 53
 54[lib]
 55crate-type = ["cdylib"]
 56
 57[dependencies]
 58zed_extension_api = "0.0.6"
 59```
 60
 61Make sure to use the latest version of the [`zed_extension_api`](https://crates.io/crates/zed_extension_api) available on crates.io.
 62
 63In 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:
 64
 65```rs
 66use zed_extension_api as zed;
 67
 68struct MyExtension {
 69    // ... state
 70}
 71
 72impl zed::Extension for MyExtension {
 73    // ...
 74}
 75
 76zed::register_extension!(MyExtension);
 77```
 78
 79## Developing an Extension Locally
 80
 81When developing an extension, you can use it in Zed without needing to publish it by installing it as a _dev extension_.
 82
 83From the extensions page, click the `Install Dev Extension` button and select the directory containing your extension.
 84
 85If you already have a published extension with the same name installed, your dev extension will override it.
 86
 87## Publishing your extension
 88
 89To publish an extension, open a PR to [this repo](https://github.com/zed-industries/extensions).
 90
 91In your PR, do the following:
 92
 931. Add your extension as a Git submodule within the `extensions/` directory
 942. Add a new entry to the top-level `extensions.toml` file containing your extension:
 95
 96```toml
 97[my-extension]
 98submodule = "extensions/my-extension"
 99version = "0.0.1"
100```
101
1023. Run `pnpm sort-extensions` to ensure `extensions.toml` and `.gitmodules` are sorted
103
104Once your PR is merged, the extension will be packaged and published to the Zed extension registry.