ES

Chrome extensions

JumPHP makes, checks, runs, tests and packs Chrome extensions (Manifest V3, plain JavaScript), on any folder: no JumPHP project needed around it, no Node or Chrome on your computer. Everything runs in Docker, in Puppeteer's image (ghcr.io/puppeteer/puppeteer:24.10.0: Node 22 + Chrome for Testing 137, pinned; JUMPHP_CHROME_IMAGE to change it), as your user. Script: tools/chrome.sh (+ tools/chrome/*.cjs); template: skeleton-chrome/.

In the JumPHP IDE: New Project > Chrome extension (a name, a folder), then the Run menu of the project: Check, Run in Chrome (screenshots open in the IDE), Test, Pack, Bump the version, ESLint. A folder with a manifest.json whose manifest_version is 3 at its root is recognised as a Chrome extension when opened.

Commands

Command
bin/jumphp chrome:new <folder> ["Name"] a new extension from skeleton-chrome/, the name in its locales, git init
bin/jumphp chrome:check [folder] [--json] the checks below; var/chrome-check.json; exit 1 on errors
bin/jumphp chrome:run [folder] [url] headless Chrome with the extension loaded unpacked: prints its id and every console error (service worker, page, popup, options); screenshots var/screenshots/page.png (1280x800), options.png (1280x800), popup.png (its own size). Without url, https://example.com/ is served from tests/fixtures/page.html (offline). Exit 1 on an error
bin/jumphp chrome:test [folder] node --test on tests/*.test.* (Puppeteer available, tests/helpers.cjs launches Chrome with the extension)
bin/jumphp chrome:pack [folder] dist/<name>-<version>.zip for the Chrome Web Store: check first, then every file but the development ones (tests/ scripts/ var/ dist/ store/ node_modules/ .git, *.md, eslint.config.*, package*.json, source maps, keys) and what .packignore lists (folder/, a/path, *.ext)
bin/jumphp chrome:bump [folder] [patch|minor|major|x.y.z] the version of manifest.json (its formatting kept)
bin/jumphp chrome:icons [folder] [#background] [#highlight] icons/icon-16/32/48/128.png drawn again by scripts/icons.cjs (pure Node)
bin/jumphp chrome:lint [folder] ESLint 10 with the project's eslint.config.mjs (npm downloads it once into ~/.cache/jumphp/chrome-npm)

The folder defaults to the current one; a relative path is relative to where the command is typed.

What chrome:check checks

  • manifest.json: valid JSON, manifest_version 3, name (75 characters at most), version (1 to 4 numbers 0-65535, no leading zero), description (132 at most), short_name (12).
  • Manifest V3 rules: no browser_action / page_action, no background.scripts / page / persistent, content_security_policy as an object without unsafe-eval / remote sources, web_accessible_resources as objects with matches, hosts in host_permissions (not permissions), no webRequestBlocking, no inline <script> nor onclick="" in pages, no remote <script src>, no eval / new Function, no remote imports.
  • Files: every file the manifest names (icons, popup, options, service worker, content scripts, side panel, devtools page, overrides, web accessible resources, rule sets, sandbox pages), the scripts / styles / images pages use, the relative imports of the scripts.
  • Icons: PNG, their real size equals their key; 16 / 48 / 128 present (128: the Web Store).
  • Permissions: unknown ones (error), sensitive ones (tabs, history, cookies, webRequest... warning), every site (<all_urls>, *://*/*: warning), declared but never used (chrome.<api> absent: warning), used without being declared (error).
  • Translations: default_locale and _locales/<lang>/messages.json together; every key used (__MSG_key__ in the manifest and pages, data-i18n / data-i18n-attr, getMessage('key') / t('key')) in every locale (missing in the default locale: error; in another: warning), the same keys everywhere, $PLACEHOLDERS$ defined, key names.

The JSON report: {ok, name, version, description, manifest_version, permissions, host_permissions, errors: [{code, message}], warnings: [...], info: [...]}.

The template

skeleton-chrome/ is a small but complete extension, a word highlighter, to replace with yours:

manifest.json name / description from _locales, icons, action with popup, options page, module service worker, a content script on example.com, permissions storage activeTab contextMenus alarms
background.js messages (getSettings, count -> the badge of the toolbar button), a context menu on selections, a periodic alarm
content/ highlights the word in the page, a floating badge with the count, re-highlights when the settings change
popup/ the word, "Highlight on this page" (a message to the tab's content script), the count, the options link
options/ word, colour, automatic: chrome.storage.sync
lib/ settings.js (defaults, get / save), i18n.js (data-i18n attributes), base.css (light / dark)
_locales/en, fr every text
icons/, scripts/icons.cjs generated icons (no brand) and their generator
tests/ 4 tests in a real Chrome (popup, options saved, content script, popup <-> tab), fixtures/page.html
README.md, AGENTS.md, PRIVACY.md loading unpacked, permissions advice, the Chrome Web Store checklist, the rules for an AI, a privacy policy to adapt
.gitignore, eslint.config.mjs

Tip for tests: the popup acts on the active tab, or on popup.html?tab=<id> (ext.tabId(page) in the helpers): a popup opened as a page in a test is itself the active tab.

Chrome Web Store checklist

  1. Developer account (one-time fee), 2-step verification.
  2. chrome:check without error, chrome:test passes, chrome:run without console error, chrome:bump.
  3. chrome:pack, upload dist/*.zip (https://chrome.google.com/webstore/devconsole).
  4. Listing: description, 128x128 icon (96x96 drawing, 16 px margin), at least one screenshot 1280x800 (or 640x400: chrome:run's page.png), small promo tile 440x280 (marquee 1400x560 optional), category, language.
  5. Privacy: the single purpose, a justification per permission, the data use declarations, the privacy policy's public address (PRIVACY.md published).
  6. Visibility (public, unlisted, private), Submit for review. Publishing is always the user's own click.

Limits

  • Headless Chrome cannot open the real toolbar popup: chrome:run and the tests open popup.html as a page.
  • Chrome for Testing in the image is the one Puppeteer 24.10 pins (137): branded Chrome 137+ ignores --load-extension, Chrome for Testing does not.
  • On Windows (Git Bash) the folders are mounted with cygpath; Docker Desktop must share the drive.
  • The IDE runs these through its own copy of JumPHP (~/.jumphp/toolkit, like the web sites): that copy must be a JumPHP that has tools/chrome.sh.
  • chrome:check reads the code with patterns, not a JavaScript parser: an API reached in an unusual way (chrome['tabs']) is not seen.