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_version3,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, nobackground.scripts/page/persistent,content_security_policyas an object withoutunsafe-eval/ remote sources,web_accessible_resourcesas objects withmatches, hosts inhost_permissions(notpermissions), nowebRequestBlocking, no inline<script>noronclick=""in pages, no remote<script src>, noeval/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_localeand_locales/<lang>/messages.jsontogether; 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
- Developer account (one-time fee), 2-step verification.
chrome:checkwithout error,chrome:testpasses,chrome:runwithout console error,chrome:bump.chrome:pack, uploaddist/*.zip(https://chrome.google.com/webstore/devconsole).- Listing: description, 128x128 icon (96x96 drawing, 16 px margin), at least one screenshot 1280x800 (or 640x400:
chrome:run'spage.png), small promo tile 440x280 (marquee 1400x560 optional), category, language. - Privacy: the single purpose, a justification per permission, the data use declarations, the privacy policy's
public address (
PRIVACY.mdpublished). - 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:runand the tests openpopup.htmlas 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 hastools/chrome.sh. chrome:checkreads the code with patterns, not a JavaScript parser: an API reached in an unusual way (chrome['tabs']) is not seen.