np-kb-chrome-extension-publishing

name	np-kb-chrome-extension-publishing
description	Rules for organizing assets in a Chrome MV3 extension repo and the Chrome Web Store submission asset checklist. Use when adding icons or promo art, packaging a build for upload, or auditing whether a repo is ready for store submission.

Chrome extension publishing

For any Manifest V3 Chrome extension repo. Project-specific CLAUDE.md files override where they conflict.

1. What ships in the bundle vs. what stays in source

Crxjs and Vite-style bundlers copy only files that are referenced from the manifest or imported by source. Use this to your advantage:

File class	Lives in	Referenced from manifest?	Ends up in dist/?
Toolbar / store icons (16, 32, 48, 128)	assets/images/	Yes — action.default_icon and top-level icons	Yes
README header, social card, marquee, promo tiles, favicons, design source PNGs	same assets/images/	No	No

Keep both classes in the same folder. The bundler's reachability analysis keeps the shipped extension small without needing a separate marketing/ directory. Verify with npm run build && find dist -type f after adding any new image.

Anti-pattern: putting promo art under public/ (everything in public/ is copied wholesale, regardless of references — Vite default).

2. Chrome Web Store submission asset checklist (MV3, 2025)

Full asset checklist, screenshot bit-depth gotcha, auth-free mockup approach, and resize notes: references/store-submission-checklist.md

3. Packaging command pattern

A single command produces both the load-unpacked-equivalent archive and the Chrome Web Store upload zip:

npm run build && \
NAME=$(node -p "require('./package.json').name") && \
VERSION=$(node -p "require('./package.json').version") && \
(cd dist && zip -r "../${NAME}-v${VERSION}.zip" .)

Use shell variables, not nested $(node -p '...') inside the path. The nested form (cd dist && zip -r "../$(node -p 'require(\"../package.json\").version').zip" .) silently produces a zip named meet-formatter-v.zip (empty version) because the escaped double-quotes break inside bash's double-quoted string. Always materialize the version into a shell var first, then interpolate.

Add *-v*.zip (or the specific name) to .gitignore so build artifacts don't get committed. Confirm with unzip -l that manifest.json is at the zip root, not nested under a dist/ folder — the CWS uploader rejects nested manifests.

4. Manifest sanity checks before submission

• description is ≤132 characters. CWS silently truncates the rest in the listing header — there's no rejection, no warning. Test the byte count in CI / build script: node -p 'JSON.parse(require("fs").readFileSync("dist/manifest.json","utf8")).description.length' should be ≤132.
• Start version low. For the very first submission, set version to something like 0.9.0 or 0.0.0.1 so you have lots of room to bump. CWS rejects re-uploads of the same version, so every iteration during review or after launch must bump. Starting at 1.0.0 works but burns your headroom on day one.
• version is bumped from the last submission (CWS rejects re-uploads of the same version).
• host_permissions are as narrow as possible — <all_urls> triggers a much slower review.
• If using host_permissions, the manifest must NOT also use activeTab for the same purpose — pick one.

5. Hand-off build at the end of every change cycle

When you finish a batch of extension changes, always rebuild dist/ and repackage the zip, then hand it to the user for manual testing — don't leave them on a stale artifact. Treat "produce a fresh installable build" as the last step of the cycle, the same way you'd run the test suite.

• Bump the version on EVERY hand-off — even a test-only / no-code-change build. Chrome keys "is this an update?" off manifest.version, and the user verifies what they loaded by reading the version in chrome://extensions. Handing off the same version twice is indistinguishable on reload — the user can't tell the fresh build from the stale one and reports a fix as "still broken" (this bit us twice: two 0.10.0s, then two 0.10.1s). So bump on each delivery (npm version patch --no-git-tag-version and the version in manifest.config.ts/manifest), even if the code is byte-identical — the point is a unique, verifiable marker. It's cheap and pre-release; consolidate at actual submission.
• Tell them how to load it cleanly: remove the old unpacked extension first, load the new zip/dist/, then reload the host tab (a content-script change only reaches already-open tabs after reload or SW re-injection).
• Rebuild from a clean tree at a known commit so the artifact matches what's pushed; the zip is gitignored (*-v*.zip).

6. Migrate stored data across updates — chrome.storage survives upgrades

When a new version changes the shape of persisted data, old storage survives and must be read-migrated — never wiped. This is the MV3 instance of the general rule in [[np-kb-coding-rules]] §7.

Migration pattern, worked example, and upgrade-test requirements: references/storage-migration.md

See also

• [[np-kb-chrome-extension-content-script]] — defensive patterns for MV3 content scripts (context invalidation, recycled-DOM idempotency)
• [[np-kb-github-pages-custom-domain]] — host the required PRIVACY.md on a custom subdomain
• [[np-kb-coding-rules]] — the long-form canon; apply on top of these for any code changes