winzik/skeleton-chrome/README.md

3.6 KiB

{{NAME}}

A Chrome extension (Manifest V3), made with JumPHP's template (bin/jumphp chrome:new). As it is, it highlights a word on the pages of example.com: replace that with what your extension does.

What is in it

File
manifest.json name, version, icons, toolbar button (popup), options page, service worker, content script, permissions
background.js the service worker: messages, a context menu, an alarm (it sleeps when idle: state goes to chrome.storage)
content/ the content script and its CSS, injected into the pages of content_scripts.matches
popup/ the toolbar button's page
options/ the options page, saved with chrome.storage.sync
lib/ code shared by the pages and the worker (ES modules): settings, translation, base CSS
_locales/en, _locales/fr the texts (__MSG_key__ in the manifest, data-i18n="key" in pages, chrome.i18n.getMessage() in code)
icons/ 16, 32, 48, 128 px PNG (drawn by scripts/icons.cjs: bin/jumphp chrome:icons . '#5b4bdb' '#ffe066')
tests/ tests in a real Chrome (Node's test runner + Puppeteer), tests/fixtures/page.html served as example.com
PRIVACY.md a privacy policy to adapt and publish (the Chrome Web Store asks for its address)

Try it

In Chrome: chrome://extensions > Developer mode (top right) > Load unpacked > this folder. After a change: the reload arrow on its card (a content script also needs the page reloaded). The service worker's console: the "service worker" link on the card; the popup's: right click on the popup > Inspect.

Without opening Chrome, everything in Docker (JumPHP's bin/jumphp, or the JumPHP IDE's Run menu):

bin/jumphp chrome:check .     # manifest, files, icons, permissions, translations
bin/jumphp chrome:run .       # headless Chrome: id, console errors, var/screenshots/page.png, popup.png, options.png
bin/jumphp chrome:test .      # tests/*.test.cjs
bin/jumphp chrome:bump . minor
bin/jumphp chrome:pack .      # dist/<name>-<version>.zip for the Chrome Web Store

Permissions

Ask for the fewest: each one adds a line to the install dialog and time to the review.

  • activeTab rather than tabs or host permissions: access to the tab the user clicked the button on, nothing else.
  • Content scripts on the sites you need, not <all_urls>; optional permissions (optional_permissions, chrome.permissions.request() from a click) for features few people use.
  • storage, alarms, contextMenus show no warning. tabs, history, cookies, webRequest, <all_urls>... do.
  • No remote code: every script is in the package (no <script src="https://...">, no eval).

Chrome Web Store checklist

  1. A developer account (https://chrome.google.com/webstore/devconsole, a one-time fee), 2-step verification on.
  2. bin/jumphp chrome:check . without errors, chrome:test passes, the version bumped.
  3. bin/jumphp chrome:pack . and upload dist/*.zip.
  4. Store listing: the description (what it does, for whom), a 128x128 icon (96x96 drawing + 16 px margin: icons/icon-128.png), at least one screenshot 1280x800 (or 640x400; chrome:run makes var/screenshots/page.png at 1280x800), a small promo tile 440x280 (optional marquee 1400x560), the category, the language.
  5. Privacy tab: the single purpose in one sentence, why each permission is needed, the data use declarations (what is collected: here nothing), and the privacy policy's address (PRIVACY.md published somewhere).
  6. Distribution: public, unlisted or private; then Submit for review (a few days; longer with sensitive permissions).