# Extensions

> Write a KazoCode extension in TypeScript - register commands, read and write workspace files, show messages, add languages - then test it locally and publish it to the marketplace.

An extension is a folder with a `package.json` and a script whose `activate(context)` function runs inside KazoCode. Types come from `@kazocode/sdk/extension`, the same ones KazoCode itself uses.

## Create one

```sh
npx kazocode-sdk new extension word-count --publisher acme
```

```ts title="src/extension.ts"
import type { ExtensionContext } from "@kazocode/sdk/extension";

export function activate(kazo: ExtensionContext) {
  kazo.commands.register("acme.word-count.count", async () => {
    const text = await kazo.workspace.readFile(kazo.workspace.resolve("README.md"));
    kazo.window.showInformationMessage(`README has ${text.split(/\s+/).length} words`);
  });
}
```

## The manifest

```json title="package.json"
{
  "id": "acme.word-count",
  "name": "word-count",
  "publisher": "acme",
  "displayName": "Word Count",
  "version": "0.1.0",
  "main": "dist/extension.js",
  "contributes": {
    "commands": [{ "command": "acme.word-count.count", "title": "Count Words in README" }],
    "languages": [{ "id": "toml", "extensions": ["toml"], "module": "dist/toml.js" }]
  }
}
```

`id` is `publisher.name` in lower case and `version` is a semantic version.

## What the context offers

| Member | For |
| --- | --- |
| `commands` | Register commands for the command palette and shortcuts |
| `workspace` | Resolve paths, and read, write and list files in the open project |
| `window` | Show information, warning and error messages |
| `languages` | Register a CodeMirror language for file extensions |
| `log` | Write to the Output panel |
| `subscriptions` | Things to clean up when the extension is turned off |

See `ExtensionContext` in `@kazocode/sdk/extension` for every member.

## Try it locally

Build the extension, copy the folder to `~/.kazocode/extensions/<publisher>.<name>`, and reload KazoCode.

## Publish

Check the extension the way the marketplace will:

```sh
npx kazocode-sdk validate ./word-count
```

The marketplace reads GitHub repositories. Put `.kazocode/marketplace.json` at the root of a repository, listing your extension folders:

```json title=".kazocode/marketplace.json"
{ "name": "Acme Tools", "owner": { "name": "Acme" }, "plugins": [{ "source": "./extensions/word-count" }] }
```

`npx kazocode-sdk new marketplace acme-tools --publisher acme` creates one for you. Commit your built `dist` files, push, and add the repository as a source in KazoCode's Extensions view. An extension can have at most 300 text files, 512 KB each and 4 MB in total.
