byarielm.fyi / atlast
ATlast — you'll never need to find your favorites on another platform again. Find your favs in the ATmosphere.
atproto
fork atom
atlast / packages / extension /
at master 1 folder 10 files
src
FIREFOX.md
README.md
build.js
manifest.chrome.json
manifest.firefox.json
manifest.json
package.json
postcss.config.js
tailwind.config.js
tsconfig.json
README.md

ATlast Importer - Browser Extension#

Browser extension for importing Twitter/X follows to find them on Bluesky.

Development#

Prerequisites:

  • ATlast dev server must be running at http://127.0.0.1:8888
  • You must be logged in to ATlast before using the extension

Build Extension#

# From project root:
cd packages/extension
pnpm install
pnpm run build        # Dev build (uses http://127.0.0.1:8888)
pnpm run build:prod   # Production build (uses https://atlast.byarielm.fyi)

The built extension will be in dist/chrome/.

Load in Chrome for Testing#

  1. Open Chrome and navigate to chrome://extensions
  2. Enable Developer mode (toggle in top right)
  3. Click Load unpacked
  4. Select the packages/extension/dist/chrome/ directory
  5. The extension should now appear in your extensions list

Testing the Extension#

Step 0: Start ATlast Dev Server#

# From project root:
npx netlify-cli dev --filter @atlast/web
# Server will start at http://127.0.0.1:8888

Then open http://127.0.0.1:8888 and log in with your Bluesky handle.

Step 1: Navigate to Twitter Following Page#

  1. Open Twitter/X in a new tab
  2. Go to https://x.com/{your-username}/following
    • Replace {your-username} with your actual Twitter username
    • Example: https://x.com/jack/following

Step 2: Open Extension Popup#

  1. Click the ATlast Importer icon in your browser toolbar
  2. You should see "Ready to scan Twitter/X" state
    • If you see "Go to x.com/following to start", the page wasn't detected correctly
    • Check the browser console for [ATlast] log messages to debug

Step 3: Scan Following Page#

  1. Click Start Scan button
  2. The extension will:
    • Scroll the page automatically
    • Collect usernames as it scrolls
    • Show progress (e.g., "Found 247 users...")
  3. Wait for "Scan complete!" message

Step 4: Upload to ATlast#

  1. Click Open in ATlast button
  2. Extension will:
    • POST usernames to ATlast API
    • Open ATlast in a new tab with ?importId=xxx
  3. ATlast web app will:
    • Load the import data
    • Start searching Bluesky automatically
    • Show results page

Debugging#

Enable Console Logs#

Open Chrome DevTools (F12) and check the Console tab for [ATlast] messages:

Content Script logs (on x.com pages):

[ATlast] Content script loaded
[ATlast] Current URL: https://x.com/username/following
[ATlast] Host: x.com
[ATlast] Path: /username/following
[ATlast] ✅ Detected Twitter/X following page
[ATlast] ✅ Notified background: ready state

Background Worker logs (in extension service worker):

[Background] Received message: STATE_UPDATE
[Background] State updated: {status: 'ready', platform: 'twitter', pageType: 'following'}

Popup logs (when extension popup is open):

[Popup] Initializing...
[Popup] Updating UI: {status: 'ready', platform: 'twitter'}
[Popup] Ready

Common Issues#

Issue: Extension shows "Not logged in to ATlast"

Solution:

  1. Open http://127.0.0.1:8888 in a new tab
  2. Log in with your Bluesky handle
  3. Return to extension and click "Check Again"

Issue: Extension shows "ATlast server not running"

Solution:

  1. Start dev server: npx netlify-cli dev --filter @atlast/web
  2. Wait for server to start at http://127.0.0.1:8888
  3. Click "Check Again" in extension

Issue: Popup shows "Go to x.com/following" even when on following page

Possible causes:

  1. Content script didn't load (check for console errors)
  2. URL pattern didn't match (check console for pattern mismatch)
  3. Background worker didn't receive state update

Debug steps:

  1. Open DevTools Console on the Twitter page
  2. Look for [ATlast] Content script loaded message
  3. Check if pattern matched: [ATlast] ✅ Detected Twitter/X following page
  4. If no detection, check [ATlast] Supported patterns output

Issue: Extension doesn't show in toolbar

  1. Go to chrome://extensions
  2. Verify ATlast Importer is enabled
  3. Click the puzzle piece icon (extensions menu)
  4. Pin ATlast Importer to toolbar

Issue: Scan doesn't find any users

  1. Make sure you're scrolled to the top of the following page
  2. Check that usernames are visible on the page (not loading state)
  3. Open Console and look for scraping logs during scan

Production Build#

For production deployment (Chrome Web Store):

cd packages/extension
pnpm run build:prod  # Uses production API URL
cd dist/chrome
zip -r ../chrome.zip .

Upload dist/chrome.zip to Chrome Web Store.

Note: Production build connects to https://atlast.byarielm.fyi instead of local dev server.

Architecture#

  • Content Script (src/content/index.ts) - Runs on x.com, detects page, scrapes usernames
  • Background Worker (src/background/service-worker.ts) - Manages state, coordinates messaging
  • Popup UI (src/popup/) - User interface when clicking extension icon
  • Scrapers (src/content/scrapers/) - Platform-specific scraping logic (Twitter, future: Threads, etc.)
  • Messaging (src/lib/messaging.ts) - Communication between components
  • API Client (src/lib/api-client.ts) - Uploads data to ATlast API

Future Enhancements#

  • Firefox support (Manifest V2/V3 compatibility)
  • Threads.net scraper
  • Instagram scraper
  • TikTok scraper
  • Auto-navigate to following page button
  • Username detection from DOM
  • Safari extension (via iOS app wrapper)