First Chrome Web Store submission

Step 5 of the getting-started journey: the runbook for your first Chrome Web Store (CWS) submission with this kit. Work top to bottom; nothing here assumes a previous publication.

1. Developer account

1. Sign in to the Chrome Web Store Developer Dashboard with the Google account that will own the listing.
2. Pay the one-time $5 registration fee and verify your email.
3. Turn on two-factor authentication for the account. A phished publisher account, not code, is how the Cyberhaven compromise (Dec 2024) pushed a malicious update to 400k users. Longer term, use a group publisher with minimal members and publish from CI with scoped API credentials, never from laptops.

2. Build the zip

pnpm zip

wxt zip builds production and produces the store-ready zip in apps/extension/.output/ (the filename embeds the manifest version, e.g. …-1.0.0-chrome.zip). Before uploading, run the kit’s own gate:

pnpm audit:remote-code

3. Minimize permissions first

Every permission adds install-warning friction and review time. WXT generates a minimal manifest and pruned modules take their permissions with them, but review two items yourself before submitting:

• The content script matches https://*/* out of the box. That broad host pattern exists only for the highlighter demo and is the single biggest review-time item in the kit. Narrow matches to the sites your product actually operates on, or switch to programmatic injection with activeTab (user-invoked, zero install-time host warning).
• Every remaining permission needs a one-line justification in the listing’s privacy tab. The kit’s defaults and their rationales:

permission	why it’s there	drop it when
storage	every store/state primitive	never (core)
identity	Google sign-in (launchWebAuthFlow + getAuthToken fast path)	you remove Google sign-in entirely
offscreen	offscreen signInWithPopup fallback	you set WXT_GOOGLE_OAUTH_CLIENT_ID and delete the fallback
alarms	service-worker-safe timers (gate event flush, error flush)	you remove the gate module and use no alarms
sidePanel	the sidepanel surface	you remove the sidepanel entrypoint
tabs	reading changeInfo.url in the OAuth window-focus workaround	you drop the offscreen fallback

Never request <all_urls>, webRequest, cookies, history, or management “for later”: each is a review escalator; add them with the feature that needs them.

4. Create the listing

Store listing tab: name, description, at least one 1280×800 or 640×400 screenshot, the 128×128 icon, category, and language. (pnpm store-assets generates promo-image scaffolding.) Write the description around your single purpose. CWS policy expects one narrow, clear purpose, and the listed functionality must work on a fresh install; the paywalls guide covers how the kit guarantees that.

5. The privacy practices tab

This tab is mandatory and a common cause of “can’t submit” confusion; every field must be filled:

1. Single purpose: one sentence describing what the extension does.
2. Permission justifications: one per permission; use the table above.
3. Data usage: what user data you collect, mapped to CWS’s categories. Paste the kit’s exact answers from Privacy disclosures.
4. Certifications: the three compliance checkboxes; Privacy disclosures walks through why the unmodified kit satisfies each.
5. Privacy policy URL: required as soon as you collect any user data (with auth enabled, you do). Host one at the URL configured in site.config.ts → urls.privacy.

6. Submit, and what to expect

• Typical review time is hours to a few days. Broad host permissions and newer developer accounts routinely stretch that, up to a few weeks in the worst cases. Don’t plan a launch date on review completing overnight.
• You can choose deferred publish: get approved first, press publish when you’re ready.
• Staged rollout publishes to a percentage of users. The dashboard offers it only for items with a large existing install base, so it won’t apply to submission #1. Verify the current eligibility threshold against the CWS docs.
• If you’re rejected, the email names a rejection reason. Look it up in Rejection codes for what triggered it and how to recover.

7. After approval

• Monitor the listing for unexpected versions (supply-chain hygiene).
• Later releases can go through CI: pnpm submit wraps publish-browser-extension and reads store credentials from the environment (submit:dry validates credentials without uploading).
• Broadcasts (guide) let you talk to installs while a review is pending; announcements are remote data, which is allowed.