Skip to main content
A cross-browser extension submits to several stores, and every store asks for the same paperwork: listing copy, permission justifications, privacy disclosures, reviewer notes, and release notes. The STORE.md convention puts all of it in one tracked file at the project root, so a resubmission never reinvents it. The file has a second job. Deployment tooling that supports the convention reads it at submission time and attaches the fields each store API accepts. Everything else stays a copy-paste reference for the store dashboards.

​
When to create it

Author STORE.md before the first submission, at the moment publishing intent appears. Submission tooling reads the file silently: when it is missing, submissions go out without reviewer notes, release notes, or certification notes, and nothing warns you. The file earns its keep by being maintained while the code changes, not written in a scramble at the end. For the full submission journey around it, see Publish to the browser stores.

​
Structure

One ## section per store, with shared material above the store sections. Store sections match by heading text, so ## Firefox Add-ons, ## firefox-amo, and ## AMO all work. The same applies to Chrome and Edge.

​
What each store reads

The Firefox and Edge submission APIs accept reviewer-facing notes, so tooling that supports STORE.md can send them for you: The Chrome Web Store accepts no listing metadata over its API, so the whole Chrome section is a reference for the developer dashboard. Its shape mirrors the sections agent tooling expects from a CHROMEWEBSTORE.md file, so an agent that looks for those sections finds them here.

​
Starter files in the templates

Nearly every Extension.js template ships a starter STORE.md generated from its own manifest; a couple of minimal templates do not, so add the file yourself if yours lacks one. The permission justifications already match the permissions the template requests, and the placeholder lines are marked TODO. Create a project from a template and the convention is in place from the first commit:

​
Keep it current

Update STORE.md in the same change that makes it stale:
  • Manifest changed (permissions, host_permissions, content_scripts): revisit every justification. Each permission needs a specific, plain-English reason. “Needed for the extension to work” fails review on every store.
  • User-facing behavior changed: refresh the listing copy and bump the last-updated date.
  • New release: add a version history entry and rewrite the release notes.
  • Data handling changed: update the privacy section, the policy it links to, and the manifest’s Firefox data_collection_permissions declaration together. The three must agree. See Firefox store readiness for the mandatory manifest key.
  • Store rejection: record the reason and the fix in version history, so the next submission does not repeat it.

​
Hygiene

  • Track the file in git. It is part of the project, not a scratch note.
  • Keep it out of the extension zip. The production build packages only dist/<browser>/, so a root-level STORE.md never ships to users.
  • Never put real user credentials in it. Reviewer test accounts are throwaway by construction.