winzik/docs/chrome-extension.md

90 lines
7 KiB
Markdown

# 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 `import`s 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.