# Plugin Repo Structure

> The files and folders a Broadcast plugin repo must have, the names it must not have, its size limits, and the plugin API version policy.

Source: https://sendbroadcast.net/docs/plugins-repo-structure

> Coming in Broadcast 3.0. Until then, this page applies only to the Upcoming (edge) build.

Each plugin is its own git repo. Make it from the template repo, `broadcast-plugin-template`. The template has every file on this page, so a new repo passes the check at once.

## The same check as the store

`broadcast-plugin check` runs the same structure rules as the plugin store. Both read one rules file in the plugin kit. If the check passes on your computer, the structure check of the store passes too.

An error stops a submission. A warning does not, but the reviewer sees it.

## Files and folders

Paths are from the root of the repo. A folder counts only when it holds at least one file with an allowed name. A `test/` folder with only a `.env` file in it does not count.

| Path | Level | Why |
|---|---|---|
| `manifest.json` | Error | It names the plugin, its version, the Broadcast versions it supports and its permissions. |
| `src/main.ts` or `src/main.js` | Error | The plugin code. One of the two must be there. |
| `README.md` | Error | The store shows it on the plugin page. |
| `LICENSE` | Error | The license of the plugin. |
| `AGENTS.md` | Error | It tells coding agents how to build the plugin. Copy it from the template. |
| `test/` | Error | Add at least one test. The template has one. |
| `CLAUDE.md` | Warning | The template's `CLAUDE.md` points Claude Code to `AGENTS.md`. |
| `kit/` | Warning | A pinned copy of the plugin kit. CI can build and test with no Broadcast server. |
| `.github/workflows/` | Warning | The template's workflow runs build, test and check on each push. |
| `.gitignore` | Warning | It keeps `dist/`, packages and secrets out of the repo. |

Names must match exactly, with the same case. `readme.md` does not count as `README.md`.

## No `dist/` folder

`dist/` is built by `broadcast-plugin build` and by the store. Remove it from the repo and add it to `.gitignore`. A `dist/` folder in the repo is a warning.

## Required manifest keys

`manifest.json` must be a JSON object. If it is not valid JSON, that is an error and the check does not look for the keys. It must have these keys:

- `id`
- `name`
- `version`
- `requires.broadcast`
- `requires.pluginApi`

A key is missing when it is not there, when it is `null`, or when it is text with only spaces. [Plugin Reference](https://sendbroadcast.net/docs/plugins-reference) explains each key.

## Names that must not be in the repo

These names are errors in any folder. The case does not matter, so `PROD.PEM` matches `*.pem`. A `*` stands for any text in the name, also no text, so `.pem` matches `*.pem` too.

| Name | Why |
|---|---|
| `node_modules` | Installed dependencies do not go in the repo. |
| `.env` and `.env.*` | A `.env` file can hold secrets. |
| `*.pem` | A key or certificate file. |
| `*.key` and `*.p12` | A key file. |
| `id_rsa` and `id_ed25519` | A private SSH key. |
| `*.broadcast-plugin` | A built package. Attach it to a release instead. |

`.env.example` and `.env.sample` are allowed. Use them to show which settings the plugin needs.

A folder with a forbidden name is one error. The check does not look into it.

The check does not read the `.git` folder at the root of the repo. A `.git` folder in a subfolder is checked like any other folder.

## Limits

- At most 2,000 files in the repo.
- At most 50 MB of files in all.

The limits count the files outside the root `.git` folder and outside folders with a forbidden name. A file with a forbidden name does not count either.

## Links

Symbolic links are not allowed. Each one is an error, and the check does not follow it.

The built package has its own, smaller limits. See [Publish a Plugin](https://sendbroadcast.net/docs/plugins-publish).

## When the store builds the repo

You can submit a plugin from its git repo. The store then runs these rules on the commit of your tag, and builds `dist/main.js` itself with esbuild 0.28.2. Code in `src/` can import only other files in `src/`. See [Submit from a git repo](https://sendbroadcast.net/docs/plugins-publish#submit-from-a-git-repo).

## Plugin API versions

The manifest says which plugin API it uses in `requires.pluginApi`. The store accepts the current major version (N) and the one before it (N-1). When a new major version ships, Broadcast serves the one before it for at least 12 months.

Today the plugin API is version 1, so `requires.pluginApi` is `"1"`.