Skip to main content

Browser Extension — Clip to CommonPlace

Save articles, quotes, and links from anywhere on the web to your CommonPlace drafts.

Overview​

The "Clip to CommonPlace" extension is a vanilla JavaScript browser extension using Manifest V3. It lets you clip web content directly into your CommonPlace account without leaving the page.

Source: extension/

Features​

  • Clip full pages — Save the current page's URL, title, and selected metadata
  • Clip selections — Highlight text and clip just that excerpt
  • Keyboard shortcuts — Alt+Shift+C (clip page), Alt+Shift+S (clip selection)
  • Context menu — Right-click to clip
  • Offline queue — Clips are queued when offline and synced when reconnected
  • oEmbed support — Rich previews for supported URLs

Architecture​

extension/
├── manifest.json          # MV3 manifest (Chrome)
├── package.json           # npm scripts for build/watch
├── build.sh               # Build Chrome/Firefox zips
├── watch.sh               # Auto-rebuild on file changes
├── assets/                # Extension icons (16, 32, 48, 128px)
├── background/
│   └── service-worker.js  # Background service worker
├── content/
│   └── content-script.js  # Injected content script
├── lib/
│   ├── api.js             # Supabase API calls
│   ├── auth.js            # Authentication
│   ├── config.js          # Configuration
│   ├── oembed.js          # oEmbed resolution
│   ├── offline-queue.js   # Offline clip queuing
│   └── utils.js           # Shared utilities
├── options/
│   ├── options.html       # Options page
│   ├── options.css
│   └── options.js
└── popup/
    ├── popup.html         # Extension popup
    ├── popup.css
    ├── popup.js
    └── auth.js            # Popup auth flow

Build Scripts​

build.sh​

Packages the extension into distributable zip files.

# Build Chrome zip (default)
bash build.sh

# Build Firefox zip (patches manifest for MV3 compatibility)
bash build.sh firefox

# Build both
bash build.sh all

Output goes to extension/dist/:

  • commonplace-chrome-v1.0.0.zip
  • commonplace-firefox-v1.0.0.zip

Cross-platform zip: The script tries zip first, then PowerShell Compress-Archive (Windows), then 7z.

Firefox manifest patching: The Firefox build automatically:

  • Replaces service_worker with scripts array (Firefox MV3 requirement)
  • Adds browser_specific_settings.gecko with addon ID

watch.sh​

Polls for file changes every 2 seconds and rebuilds automatically.

# Watch and rebuild Chrome zip
bash watch.sh

# Watch and rebuild Firefox zip
bash watch.sh firefox

npm scripts​

npm run build           # bash build.sh
npm run build:firefox   # bash build.sh firefox
npm run watch           # bash watch.sh

Development​

For local development, load the extension unpacked directly from extension/ in your browser's extension manager. The build scripts are for creating distributable packages.

Chrome​

  1. Go to chrome://extensions/
  2. Enable "Developer mode"
  3. Click "Load unpacked"
  4. Select the extension/ directory

Firefox​

  1. Go to about:debugging#/runtime/this-firefox
  2. Click "Load Temporary Add-on"
  3. Select extension/manifest.json

Permissions​

  • activeTab — Access to the current tab when the user clicks the extension
  • storage — Store auth tokens and settings
  • contextMenus — Right-click context menu integration
  • notifications — Show clip confirmation notifications
  • alarms — Schedule offline queue sync
  • Host permissions for Supabase API endpoints