Skip to content

harvard-lil/perma-extension

Repository files navigation

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+)

Test suite

📹 How does it work ?

💾 Download it on the Chrome Web Store


Summary


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 
Loading

☝️ 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

☝️ 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.

Name Context Required Description
TESTS_API_KEY Test suite Yes API key to be used for E2E tests.
CI Test suite No Will alter test reporting if set (see playwright.config.js). Used to run tests in a GitHub Action.

☝️ Back to summary


API Documentation

Automatically-generated API documentation. Uses JSDoc comments.

background

constants

popup

storage

☝️ 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:
  • 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