93 lines
4.7 KiB
Markdown
93 lines
4.7 KiB
Markdown
# Solution : Squelette de l'extension Firefox
|
|
|
|
## Problème résolu
|
|
Poser la structure minimale d'une extension Firefox (Manifest V3, **sans build
|
|
step**, vanilla JS) chargeable en module temporaire via `about:debugging` sur
|
|
NixOS (pas de signature requise en dev). Le clic sur l'icône doit ouvrir une
|
|
**page dédiée autonome** — la future liste agrégeant l'Atelier du Huit et la
|
|
ville de Cugnaux. Ce squelette ne récupère aucune donnée : il câble la chaîne
|
|
icône → page.
|
|
|
|
## Approche choisie
|
|
Entre les deux options du corps de tâche (`action.default_popup` **ou** page
|
|
dédiée), on retient la **page dédiée** ouverte dans un onglet via
|
|
`background.js` :
|
|
|
|
- « liste autonome » = vraie page plein écran, lisible, rechargeable, non
|
|
contrainte aux ~600 px d'un popup qui se ferme à la perte de focus.
|
|
- Cela donne un rôle concret à `background.scripts` (clé Firefox explicitement
|
|
demandée) : écouter `action.onClicked` et faire `tabs.create`.
|
|
- Contrainte MDN confirmée : `action.onClicked` **ne se déclenche pas** si
|
|
`default_popup` est défini → on **n'ajoute pas** `default_popup`.
|
|
|
|
Pas de dépendance runtime. Tests de forme avec `bun test` à la racine,
|
|
`web-ext lint` en contrôle dev optionnel via `bunx` (zéro dépendance ajoutée).
|
|
|
|
## Décisions clés
|
|
- **Sous-dossier `extension/`** : isole l'extension chargeable (ce que voit
|
|
`about:debugging`) du tooling bun resté à la racine (tests, `package.json`).
|
|
Séparation des concerns nette.
|
|
- **`strict_min_version: "127.0"`** : avant Firefox 127, les `host_permissions`
|
|
étaient optionnelles (non accordées à l'install). Le seuil 127 garantit
|
|
qu'elles sont accordées dès l'installation.
|
|
- **Namespace `browser.*`** (API Firefox native, basée promesses) — jamais
|
|
`chrome.*`. Cohérent dans tout le code.
|
|
- **Permission `tabs` volontairement omise** : `tabs.create` ne la requiert
|
|
pas. Principe du moindre privilège.
|
|
- **Icône SVG unique** mappée sur les tailles `48`/`96` : accepté par Firefox,
|
|
low-tech.
|
|
- **`browser_specific_settings.gecko.id`** présent : identité stable de
|
|
l'extension.
|
|
|
|
## Patterns à réutiliser
|
|
**Listener `onClicked` au niveau racine (synchrone)** — l'event page MV3 peut
|
|
être déchargée ; enregistrer le listener à la racine de `background.js` (jamais
|
|
dans un callback async) garantit qu'il est rattaché au réveil :
|
|
```js
|
|
// extension/background.js
|
|
browser.action.onClicked.addListener(() => {
|
|
browser.tabs.create({ url: browser.runtime.getURL("liste.html") });
|
|
});
|
|
```
|
|
`browser.runtime.getURL(...)` plutôt qu'une URL concaténée : robuste et sûr.
|
|
|
|
**Test de forme du manifeste (garde-fous structurels)** — `bun test` valide la
|
|
structure sans navigateur, dont le garde-fou anti-régression `default_popup`
|
|
absent :
|
|
```ts
|
|
const manifest = await Bun.file(join(extensionDir, "manifest.json")).json();
|
|
test("ne définit PAS default_popup (sinon onClicked devient muet)", () => {
|
|
expect(manifest.action.default_popup).toBeUndefined();
|
|
});
|
|
test("demande les host_permissions des deux sources", () => {
|
|
expect(manifest.host_permissions).toEqual([/* URLs exactes, ordre vérifié */]);
|
|
});
|
|
```
|
|
Vérifier aussi l'existence des ressources référencées (`existsSync`).
|
|
|
|
## Pièges à éviter
|
|
- **`default_popup` + `onClicked` incompatibles** : ajouter `default_popup` rend
|
|
`onClicked` muet → la page ne s'ouvre plus. Protégé par un test dédié.
|
|
- **`host_permissions` < FF127** : sans `strict_min_version: "127.0"`, elles ne
|
|
sont pas accordées à l'install.
|
|
- **Listener dans un callback async** : peut être manqué au réveil de l'event
|
|
page. Toujours au niveau racine.
|
|
- **Module temporaire volatil** : un add-on chargé via `about:debugging`
|
|
disparaît au redémarrage de Firefox → à recharger (nature dev, documentée
|
|
dans le README).
|
|
- **Ressource d'icône manquante** : si l'icône SVG n'est pas fournie, retirer
|
|
les clés `icons`/`action.default_icon` sinon erreur de ressource au lint.
|
|
- **Worktree sans baseline** : le worktree n'héritait pas du README/`docs/`
|
|
canoniques. Résolu par rebase sur `main` une fois la baseline réelle commitée
|
|
(`328df2d`). Penser à vérifier la baseline avant de dupliquer des fichiers.
|
|
- **Warning `MISSING_DATA_COLLECTION_PERMISSIONS`** (web-ext) : non bloquant
|
|
ici, mais Firefox recommande désormais
|
|
`gecko.data_collection_permissions: { "required": ["none"] }` pour une
|
|
extension sans collecte — à prévoir pour les prochaines.
|
|
- **Diagnostics IDE `bun:test`** : `bun test` tourne sans `tsconfig`, mais
|
|
l'éditeur signale `Cannot find module 'bun:test'` faute de `bun-types`.
|
|
Purement cosmétique (aucun impact runtime).
|
|
|
|
## Tags
|
|
tags: [firefox-extension, manifest-v3, webextension, vanilla-js, bun-test, web-ext, low-tech, nixos]
|