tom.sherman.is / frontpage_firefox_plugin
forked from anton.galiglobal.com/frontpage_firefox_plugin
Firefox WebExtension that lets you share the current tab to frontpage.fyi with minimal effort.
fork atom
JavaScript 67.1%
HTML 17.5%
CSS 12.3%
Dockerfile 3.1%
3 4 0

Clone this repository

https://tangled.org/tom.sherman.is/frontpage_firefox_plugin
git@tangled.org:tom.sherman.is/frontpage_firefox_plugin

For self-hosted knots, clone URLs may differ based on your setup.

Download tar.gz
README.md

frontpage.fyi Firefox extension#

This repository provides a Firefox WebExtension that lets you share the current tab to frontpage.fyi with minimal effort.
Links are submitted by creating fyi.unravel.frontpage.post records on your ATProto account, the same mechanism the official Frontpage site uses.

ℹ️ The Frontpage source code lives at https://tangled.org/did:plc:klmr76mpewpv7rtm3xgpzd7x/frontpage.

Features#

  • Pop-up form that auto-fills the active tab’s title and URL.
  • Title length indicator (120 characters, matching the Frontpage UI).
  • Background service worker handles ATProto login, token refresh, and record creation.
  • Options page for storing your handle, app password, and optional PDS override.
  • Convenience links to open frontpage.fyi or the options page from the pop-up.

Repository layout#

extension/
├── background.js   # Service worker for auth + ATProto requests
├── manifest.json   # Manifest V3 definition
├── options.html/js # Credential management UI
├── popup.html/js   # Submission UI
└── styles.css      # Shared styling for popup and options

Prerequisites#

Development install (temporary)#

  1. Open about:debugging#/runtime/this-firefox.
  2. Click Load Temporary Add-on… and choose manifest.json inside the extension/ directory.
  3. Pin the “Frontpage” toolbar button if you want quick access.

This method is ideal while iterating; Firefox forgets the add-on on restart.

Install a packaged build#

After the GitHub Action finishes:

  1. Download the frontpage-extension-unsigned (or frontpage-extension-signed if signing is enabled) artifact from the workflow run.
  2. If unsigned, extract the ZIP that web-ext produced and re-zip it as needed, or use the ZIP as-is for self-hosting.
  3. In Firefox, open about:addons → click the gear icon → Install Add-on From File…, then select the .zip or .xpi.
  4. Firefox will install the add-on; confirm the permissions dialog to finish.

For ongoing self-distribution, host the resulting .zip/.xpi on your own site and point Firefox users there, following Mozilla’s self-distribution guide.

Configure credentials#

  1. Open the add-on pop-up and press the gear icon (or use about:addons → Preferences).
  2. Enter your handle and app password. Supply a PDS URL only if you run a custom server.
  3. Click Save credentials. A success message confirms that the session tokens are stored locally.
  4. Use Log out at any time to remove stored tokens (you can also revoke the app password server-side).
  1. Browse to the page you want to share.
  2. Open the Frontpage pop-up; the title and URL are pre-filled.
  3. Adjust the text if necessary and click Post to Frontpage.
  4. On success, the pop-up reports the record URI returned by com.atproto.repo.createRecord.

Implementation notes#

  • The background worker discovers the user’s PDS by resolving the handle (com.atproto.identity.resolveHandle + PLC lookup).
  • Sessions are refreshed automatically via com.atproto.server.refreshSession when the access JWT expires.
  • All data stays in browser.storage.local; nothing is transmitted to third-party services beyond the ATProto endpoints.
  • Maximum lengths follow the current Frontpage limits (120 characters for the title, 2048 for URLs).

Development tips#

  • Inspect background/service-worker logs from about:debugging → Inspect.
  • The UI scripts (popup.js and options.js) log to the DevTools console attached to their respective documents.
  • When packaging for distribution, zip the contents of the extension/ directory (see workflow below).

Ship it on AMO#

  • Provide the bundled icons from extension/icons/ (16, 32, 48 and 128 px SVGs).
  • Zip the extension/ directory (e.g. cd extension && zip -r ../frontpage-submitter.zip .).
  • Upload the archive to https://addons.mozilla.org/developers/ and fill in the listing copy/screenshots.
  • AMO reviewers expect a concise summary; you can adapt the “Features” bullets above.

Self-distribution pipeline#

This repository includes .github/workflows/package-extension.yml which builds (and optionally signs) the add-on using web-ext.

  1. Configure AMO_JWT_ISSUER and AMO_JWT_SECRET repository secrets with your AMO API credentials if you want automatic signing.
    Without the secrets, the workflow still produces an unsigned ZIP you can download.
  2. Trigger the workflow manually (Actions → package-extension → Run workflow) or push changes to main.
  3. Download the artifacts:
    • frontpage-extension-unsigned contains the ZIP that web-ext build generates.
    • frontpage-extension-signed (only when secrets are present) contains the signed .xpi from AMO for self-hosting.

These artifacts can be hosted directly for self-distribution as described in the Mozilla documentation.