manifest.json at the root of the archive. Firefox Add-ons also asks for a zip of your source when the upload is minified or bundled, which a production build is. Safari is the exception: the extension ships inside a macOS or iOS app that Xcode builds. This page explains the three ways to produce the archive, names the exact files that extension build --zip writes, and lists what each store takes. It also quotes the console lines that the CLI prints while it packages.
extension.dev,
the sponsor of Extension.js, handles publishing, store submission, and sharing
from the same project. Its docs cover the steps after
extension build.The three ways to produce the archive
Zipdist/<browser> by hand. Run extension build --browser=chrome, open dist/chrome, choose its contents, and compress. The trap is the folder: a zip of the chrome folder itself puts manifest.json one level down, and the store rejects it.
extension build --zip. The build writes dist/<browser> and then packages it beside the folder, never inside it. Source maps stay out of the archive. Add --zip-source for the source archive that AMO asks for.
A CI job. The same extension build --zip command runs on a runner, and the job uploads dist/*.zip as a build artifact or hands it to a store API. Store credentials stay in CI secrets. See CI templates.
Use the manual route once, to learn what the store expects. Use
--zip for every release after that, and move the same command into CI when more than one person ships.
Command snippet
The flags belong tobuild:
extension.config.js when you want every build to package without flags:
extension.config.js
extension build --browser=chrome writes dist/store-chrome.zip and dist/store-source.zip.
What the build writes
Each archive lands indist/, beside the dist/<browser> folder. Without --zip-filename, the name is the manifest name lowercased with every character outside a-z0-9 and spaces removed, then the manifest version, then the browser. A manifest named zip-probe at version 1.0.0 packages as zipprobe-1.0.0-chrome.zip: the dash is gone, so read the path from the build output instead of composing it. From the release after 4.1.39, --zip-dir <path> writes the archives to another folder, see build. These runs used Extension.js 4.1.31:
Two rules follow from the table. The default browser is
chromium, so pass --browser=chrome when the Chrome Web Store is the target. And --zip-filename alone never writes a source archive: --zip-source does. The explicit name then governs both files, with the browser appended to the distribution archive and -source to the other.
The distribution archive holds the contents of dist/<browser> minus .map files, with manifest.json at the root. The source archive holds the project folder minus node_modules, .git, dist, the extensions/ companion folder, every .env* file except *.example, and whatever your .gitignore excludes. Symbolic links are skipped with a warning, because an archive stores files.
Under --output json, each archive is listed in zip_artifacts with its kind (dist or source), path, and size in bytes, so a CI step can read the file path without parsing the console.
Per-browser differences
Firefox self-distribution is the one case where the store hands a file back. AMO signs the upload and emails you when the signed copy is ready to download from your submissions page. Chrome and Edge never return a
.crx, and Extension.js does not write .crx or .xpi files: the stores take the zip.
Opera’s store rejects minified code, so extension build --browser=opera turns --minify off by default.
Console lines you will see
Copy the line that you see into search. Each one maps to one cause.Packaged dist/zipprobe-1.0.0-chrome.zip (34.2 KB).
The distribution archive was written. The path is the file to upload, and its name may not match your manifest name because of the sanitizing rule above.
Packaged dist/zipprobe-1.0.0-source.zip (37.2 KB).
The source archive was written. It prints before the distribution archive on the same run. When you build several browsers it prints once per browser, because the source is the same for every browser.
Skipped the addons.mozilla.org lint: addons-linter is not installed. Install it with: npm install -D addons-linter or pass --no-addon-lint to silence this.
A Firefox build finished without the AMO lint. The zip is complete. Install addons-linter to see what AMO would flag before you upload, or pass --no-addon-lint to stop the line.
Edge Add-ons refuses a package whose manifest carries key, so dist/zipprobe-1.0.0-edge.zip leaves it out.
The store zip was written without the top-level key field, because Partner Center assigns the extension ID and refuses a package that carries one. dist/edge keeps the field, so an unpacked install of that folder keeps the ID the key pins and the OAuth redirect URL built from it stays valid. The line prints once per Edge --zip build. This behavior needs 4.1.39 or later, earlier builds dropped the field from dist/edge as well.
manifest.json description runs 133 characters, and the Chrome Web Store refuses a chrome build whose description is over 132.
The manifest description is longer than the store accepts. Chromium builds (chrome, edge, brave, opera and the other Chromium browsers) check it against 132 characters. Safari builds check it against 112, the App Store Connect limit, and that line adds (Apple error 90849). Firefox builds check it against 250, the addons.mozilla.org summary limit, which addons-linter 10.14.0 and later report as JSON_INVALID. Shorten the field to the limit that the line names. The build still finishes, so the store is the first place that refuses the upload. In dev each distinct warning prints once per session. A production build prints it on every run.
manifest.json has no description, and App Store Connect refuses a safari build without one (Apple error 90849).
A Safari build found no description in the manifest, or only whitespace. App Store Connect requires one, so add a description of 112 characters or fewer. Chromium builds do not warn about a missing description. Firefox builds do not warn about a missing description either. A localized value such as __MSG_extDescription__ is also skipped, because its text lives in _locales, so check the length of each translation yourself.
default_locale is set, but the _locales folder is missing.
The manifest check stopped the build before packaging. Stores reject a package without its default locale, so restore _locales/<default>/messages.json and build again.
The source zip skipped a symlink, because an archive stores files.
A symbolic link inside the project was left out of the source archive. Copy what the link points at into the project if the archive needs it.
The source zip was requested and not created.
The build finished and the source archive did not. The line names the path and the reason. The distribution archive is unaffected, because the two archives fail independently.
The Extension.js way
Package from the command, not from a file manager:- Run
extension build --browser=<browser> --zipfor every store, and add--zip-sourcewhen the store is Firefox Add-ons. - Pass
--zip-filename=releasein CI so the artifact name is stable, and let the CLI append the browser. - Read the archive path from the
Packagedline or fromzip_artifactsunder--output json, never from the manifestname. - Keep
dist/out of git. The build cleansdist/<browser>on every run. The archives of earlier runs never enter the next source archive. - Author STORE.md before the first upload, so reviewer notes and the AMO build instructions travel with the code.
pack command, and extension publish is a share link on extension.dev, not a store submission. See Publish command.

