perma-extension

A browser extension for Perma.cc. Create and manage Perma links directly from the browser.

• Current version: 2.0.2
• Browsers currently supported: Google Chrome (100+)

📹 How does it work ?

💾 Download it on the Chrome Web Store

Summary

• Architecture
• Development Setup
• Environment variables
• API Documentation
• CLI
• Building and distributing the extension
• Automation

Architecture

flowchart RL
    A[Service Worker]
    B[(browser.storage.local)]
    C[Popup UI<br>Custom Elements]
    D[Perma.cc API]
    A <--> B 
    B --> |onChanged events| C
    C -.-> |Runtime Messages| A
    D <--> |HTTP| A 

• This projects uses browser.storage.local - made available by the Web Extensions API - to persist data and monitor changes.
• By design, only the Service Worker interacts directly with storage, using data classes to normalize the nature of the data being stored and retrieved.
• The front-end sends runtime messages to the service worker, which reacts accordingly. _(See: list of available message ids.)_
• The front-end is made of "bare" Custom Elements, taking data as HTML attributes, which they observe and react to.
• handlers/onStorageUpdate is executed every time storage is updated. It determines what was updated, and what part of the UI needs to be re-hydrated.

☝️ Back to summary

Development Setup

Getting started

• Make sure you have the latest version of Node JS installed on your machine (18+ recommended).
• Run npm install to install dependencies.
• Use npm run dev to start "development" mode. This effectively starts vite build --watch, creating a new build under /dist every time a file changes.

Google Chrome: Install the work-in-progress extension

• Open a new tab to chrome://extensions
• Make sure to activate the "Developer Mode" toggle.
• Click on "Load unpacked" and select the dist folder in perma-extension.

Misc

• This project uses /*html*/ to indicate that a JavaScript template string contains HTML. For VSCode users, we recommend the es6-string-html extension to enable syntax highlighting in that context.

☝️ Back to summary

Environment Variables

Scope: E2E testing

The following environment variables are only used in the context of the test suites. They may be provided using an .env file, which the Playwright test runner will take into account.

☝️ Back to summary

API Documentation

Automatically-generated API documentation. Uses JSDoc comments.

background

• index.js (Entry point)
• archiveCreate.js
• archiveDelete.js
• archivePullTimeline.js
• archiveTogglePrivacyStatus.js
• authCheck.js
• authSignIn.js
• authSignOut.js
• foldersPick.js
• foldersPullList.js
• statusCleanUp.js
• tabSwitch.js

constants

• index.js (Entry point)

popup

• index.js (Entry point)
• popup/components
  • AppHeader.js
  • ArchiveForm.js
  • ArchiveTimeline.js
  • StatusBar.js
• popup/handlers
  • onPopupOpen.js
  • onStorageUpdate.js

storage

• index.js (Entry point)
• Archives.js
• Auth.js
• CurrentTab.js
• Folders.js
• Status.js

☝️ Back to summary

CLI

dev

npm run dev

Starts "development" mode. Effectively runs vite build --watch, creating a new build under /dist every time a file changes.

build

npm run build

Generates a new extension build under /dist.

build-and-zip

npm run build-and-zip

Generates a new extension build under /dist and generates a zip from it (perma-extension.zip).

docgen

npm run docgen

Generates documentation using JSDoc comments. Outputs as Markdown to doc. To update which files should be taken into account, check /scripts/docgen.sh.

test

npm run test

Runs the end-to-end tests suite using playwright.

☝️ Back to summary

Building and distributing the extension

Step-by-step:

• On develop:
  • Update documentation (npm run docgen)
  • Update APP version number in:
  • manifest.json
  • This README
• Commit changes to develop and create a pull request from develop to main
  • Merge to main when tests pass
• On the main branch:
  • At GitHub Level: Create a new release.
    • Using the main branch
    • Using semver as a title and tag (i.e: 2.0.1)
  • Locally:
  • Run npm run build-and-zip to generate perma-extension.zip.
• On the Chrome Web Store
  • Upload perma-extension.zip

☝️ Back to summary

Automation

The E2E test suite is run via GitHub Action on:

• Pull request to develop, main
• Push to main

☝️ Back to summary