ATlast — you'll never need to find your favorites on another platform again. Find your favs in the ATmosphere.
byarielm.fyi
atproto
1# ATlast Importer - Browser Extension
2
3Browser extension for importing Twitter/X follows to find them on Bluesky.
4
5## Development
6
7**Prerequisites:**
8- ATlast dev server must be running at `http://127.0.0.1:8888`
9- You must be logged in to ATlast before using the extension
10
11### Build Extension
12
13```bash
14# From project root:
15cd packages/extension
16pnpm install
17pnpm run build # Dev build (uses http://127.0.0.1:8888)
18pnpm run build:prod # Production build (uses https://atlast.byarielm.fyi)
19```
20
21The built extension will be in `dist/chrome/`.
22
23### Load in Chrome for Testing
24
251. Open Chrome and navigate to `chrome://extensions`
262. Enable **Developer mode** (toggle in top right)
273. Click **Load unpacked**
284. Select the `packages/extension/dist/chrome/` directory
295. The extension should now appear in your extensions list
30
31### Testing the Extension
32
33#### Step 0: Start ATlast Dev Server
34
35```bash
36# From project root:
37npx netlify-cli dev --filter @atlast/web
38# Server will start at http://127.0.0.1:8888
39```
40
41Then open `http://127.0.0.1:8888` and log in with your Bluesky handle.
42
43#### Step 1: Navigate to Twitter Following Page
44
451. Open Twitter/X in a new tab
462. Go to `https://x.com/{your-username}/following`
47 - Replace `{your-username}` with your actual Twitter username
48 - Example: `https://x.com/jack/following`
49
50#### Step 2: Open Extension Popup
51
521. Click the ATlast Importer icon in your browser toolbar
532. You should see **"Ready to scan Twitter/X"** state
54 - If you see "Go to x.com/following to start", the page wasn't detected correctly
55 - Check the browser console for `[ATlast]` log messages to debug
56
57#### Step 3: Scan Following Page
58
591. Click **Start Scan** button
602. The extension will:
61 - Scroll the page automatically
62 - Collect usernames as it scrolls
63 - Show progress (e.g., "Found 247 users...")
643. Wait for "Scan complete!" message
65
66#### Step 4: Upload to ATlast
67
681. Click **Open in ATlast** button
692. Extension will:
70 - POST usernames to ATlast API
71 - Open ATlast in a new tab with `?importId=xxx`
723. ATlast web app will:
73 - Load the import data
74 - Start searching Bluesky automatically
75 - Show results page
76
77### Debugging
78
79#### Enable Console Logs
80
81Open Chrome DevTools (F12) and check the Console tab for `[ATlast]` messages:
82
83**Content Script logs** (on x.com pages):
84```
85[ATlast] Content script loaded
86[ATlast] Current URL: https://x.com/username/following
87[ATlast] Host: x.com
88[ATlast] Path: /username/following
89[ATlast] ✅ Detected Twitter/X following page
90[ATlast] ✅ Notified background: ready state
91```
92
93**Background Worker logs** (in extension service worker):
94```
95[Background] Received message: STATE_UPDATE
96[Background] State updated: {status: 'ready', platform: 'twitter', pageType: 'following'}
97```
98
99**Popup logs** (when extension popup is open):
100```
101[Popup] Initializing...
102[Popup] Updating UI: {status: 'ready', platform: 'twitter'}
103[Popup] Ready
104```
105
106#### Common Issues
107
108**Issue: Extension shows "Not logged in to ATlast"**
109
110Solution:
1111. Open `http://127.0.0.1:8888` in a new tab
1122. Log in with your Bluesky handle
1133. Return to extension and click "Check Again"
114
115**Issue: Extension shows "ATlast server not running"**
116
117Solution:
1181. Start dev server: `npx netlify-cli dev --filter @atlast/web`
1192. Wait for server to start at `http://127.0.0.1:8888`
1203. Click "Check Again" in extension
121
122**Issue: Popup shows "Go to x.com/following" even when on following page**
123
124Possible causes:
1251. Content script didn't load (check for console errors)
1262. URL pattern didn't match (check console for pattern mismatch)
1273. Background worker didn't receive state update
128
129Debug steps:
1301. Open DevTools Console on the Twitter page
1312. Look for `[ATlast] Content script loaded` message
1323. Check if pattern matched: `[ATlast] ✅ Detected Twitter/X following page`
1334. If no detection, check `[ATlast] Supported patterns` output
134
135**Issue: Extension doesn't show in toolbar**
136
1371. Go to `chrome://extensions`
1382. Verify ATlast Importer is enabled
1393. Click the puzzle piece icon (extensions menu)
1404. Pin ATlast Importer to toolbar
141
142**Issue: Scan doesn't find any users**
143
1441. Make sure you're scrolled to the top of the following page
1452. Check that usernames are visible on the page (not loading state)
1463. Open Console and look for scraping logs during scan
147
148## Production Build
149
150For production deployment (Chrome Web Store):
151
152```bash
153cd packages/extension
154pnpm run build:prod # Uses production API URL
155cd dist/chrome
156zip -r ../chrome.zip .
157```
158
159Upload `dist/chrome.zip` to Chrome Web Store.
160
161**Note:** Production build connects to `https://atlast.byarielm.fyi` instead of local dev server.
162
163## Architecture
164
165- **Content Script** (`src/content/index.ts`) - Runs on x.com, detects page, scrapes usernames
166- **Background Worker** (`src/background/service-worker.ts`) - Manages state, coordinates messaging
167- **Popup UI** (`src/popup/`) - User interface when clicking extension icon
168- **Scrapers** (`src/content/scrapers/`) - Platform-specific scraping logic (Twitter, future: Threads, etc.)
169- **Messaging** (`src/lib/messaging.ts`) - Communication between components
170- **API Client** (`src/lib/api-client.ts`) - Uploads data to ATlast API
171
172## Future Enhancements
173
174- Firefox support (Manifest V2/V3 compatibility)
175- Threads.net scraper
176- Instagram scraper
177- TikTok scraper
178- Auto-navigate to following page button
179- Username detection from DOM
180- Safari extension (via iOS app wrapper)