Plugin Repo Structure
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:
idnameversionrequires.broadcastrequires.pluginApi
A key is missing when it is not there, when it is null, or when it is text with only spaces. Plugin 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.
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.
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".
