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+)
💾 Download it on the Chrome Web Store
- Architecture
- Development Setup
- Environment variables
- API Documentation
- CLI
- Building and distributing the extension
- Automation
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/onStorageUpdateis executed every time storage is updated. It determines what was updated, and what part of the UI needs to be re-hydrated.
- Make sure you have the latest version of Node JS installed on your machine (18+ recommended).
- Run
npm installto install dependencies. - Use
npm run devto start "development" mode. This effectively startsvite build --watch, creating a new build under/distevery time a file changes.
- Open a new tab to
chrome://extensions - Make sure to activate the "Developer Mode" toggle.
- Click on "Load unpacked" and select the
distfolder inperma-extension.
- This project uses
/*html*/to indicate that a JavaScript template string contains HTML. For VSCode users, we recommend thees6-string-htmlextension to enable syntax highlighting in that context.
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. |
Automatically-generated API documentation. Uses JSDoc comments.
- 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
- index.js (Entry point)
- popup/components
- popup/handlers
npm run dev
Starts "development" mode. Effectively runs vite build --watch, creating a new build under /dist every time a file changes.
npm run build
Generates a new extension build under /dist.
npm run build-and-zip
Generates a new extension build under /dist and generates a zip from it (perma-extension.zip).
npm run docgenGenerates documentation using JSDoc comments. Outputs as Markdown to doc.
To update which files should be taken into account, check /scripts/docgen.sh.
npm run testRuns the end-to-end tests suite using playwright.
Step-by-step:
- On
develop:- Update documentation (
npm run docgen) - Update APP version number in:
manifest.json- This README
- Update documentation (
- Commit changes to
developand create a pull request fromdeveloptomain- Merge to
mainwhen tests pass
- Merge to
- On the
mainbranch:- At GitHub Level: Create a new release.
- Using the
mainbranch - Using semver as a title and tag (i.e:
2.0.1)
- Using the
- Locally:
- Run
npm run build-and-zipto generateperma-extension.zip.
- Run
- At GitHub Level: Create a new release.
- On the Chrome Web Store
- Upload
perma-extension.zip
- Upload
The E2E test suite is run via GitHub Action on:
- Pull request to
develop,main - Push to
main