byarielm.fyi
+147
packages/extension/README.md
+147
packages/extension/README.md
···
1
+
# ATlast Importer - Browser Extension
2
+
3
+
Browser extension for importing Twitter/X follows to find them on Bluesky.
4
+
5
+
## Development
6
+
7
+
### Build Extension
8
+
9
+
```bash
10
+
cd packages/extension
11
+
pnpm install
12
+
pnpm run build
13
+
```
14
+
15
+
The built extension will be in `dist/chrome/`.
16
+
17
+
### Load in Chrome for Testing
18
+
19
+
1. Open Chrome and navigate to `chrome://extensions`
20
+
2. Enable **Developer mode** (toggle in top right)
21
+
3. Click **Load unpacked**
22
+
4. Select the `packages/extension/dist/chrome/` directory
23
+
5. The extension should now appear in your extensions list
24
+
25
+
### Testing the Extension
26
+
27
+
#### Step 1: Navigate to Twitter Following Page
28
+
29
+
1. Open Twitter/X in a new tab
30
+
2. Go to `https://x.com/{your-username}/following`
31
+
- Replace `{your-username}` with your actual Twitter username
32
+
- Example: `https://x.com/jack/following`
33
+
34
+
#### Step 2: Open Extension Popup
35
+
36
+
1. Click the ATlast Importer icon in your browser toolbar
37
+
2. You should see **"Ready to scan Twitter/X"** state
38
+
- If you see "Go to x.com/following to start", the page wasn't detected correctly
39
+
- Check the browser console for `[ATlast]` log messages to debug
40
+
41
+
#### Step 3: Scan Following Page
42
+
43
+
1. Click **Start Scan** button
44
+
2. The extension will:
45
+
- Scroll the page automatically
46
+
- Collect usernames as it scrolls
47
+
- Show progress (e.g., "Found 247 users...")
48
+
3. Wait for "Scan complete!" message
49
+
50
+
#### Step 4: Upload to ATlast
51
+
52
+
1. Click **Open in ATlast** button
53
+
2. Extension will:
54
+
- POST usernames to ATlast API
55
+
- Open ATlast in a new tab with `?importId=xxx`
56
+
3. ATlast web app will:
57
+
- Load the import data
58
+
- Start searching Bluesky automatically
59
+
- Show results page
60
+
61
+
### Debugging
62
+
63
+
#### Enable Console Logs
64
+
65
+
Open Chrome DevTools (F12) and check the Console tab for `[ATlast]` messages:
66
+
67
+
**Content Script logs** (on x.com pages):
68
+
```
69
+
[ATlast] Content script loaded
70
+
[ATlast] Current URL: https://x.com/username/following
71
+
[ATlast] Host: x.com
72
+
[ATlast] Path: /username/following
73
+
[ATlast] ✅ Detected Twitter/X following page
74
+
[ATlast] ✅ Notified background: ready state
75
+
```
76
+
77
+
**Background Worker logs** (in extension service worker):
78
+
```
79
+
[Background] Received message: STATE_UPDATE
80
+
[Background] State updated: {status: 'ready', platform: 'twitter', pageType: 'following'}
81
+
```
82
+
83
+
**Popup logs** (when extension popup is open):
84
+
```
85
+
[Popup] Initializing...
86
+
[Popup] Updating UI: {status: 'ready', platform: 'twitter'}
87
+
[Popup] Ready
88
+
```
89
+
90
+
#### Common Issues
91
+
92
+
**Issue: Popup shows "Go to x.com/following" even when on following page**
93
+
94
+
Possible causes:
95
+
1. Content script didn't load (check for console errors)
96
+
2. URL pattern didn't match (check console for pattern mismatch)
97
+
3. Background worker didn't receive state update
98
+
99
+
Debug steps:
100
+
1. Open DevTools Console on the Twitter page
101
+
2. Look for `[ATlast] Content script loaded` message
102
+
3. Check if pattern matched: `[ATlast] ✅ Detected Twitter/X following page`
103
+
4. If no detection, check `[ATlast] Supported patterns` output
104
+
105
+
**Issue: Extension doesn't show in toolbar**
106
+
107
+
1. Go to `chrome://extensions`
108
+
2. Verify ATlast Importer is enabled
109
+
3. Click the puzzle piece icon (extensions menu)
110
+
4. Pin ATlast Importer to toolbar
111
+
112
+
**Issue: Scan doesn't find any users**
113
+
114
+
1. Make sure you're scrolled to the top of the following page
115
+
2. Check that usernames are visible on the page (not loading state)
116
+
3. Open Console and look for scraping logs during scan
117
+
118
+
## Production Build
119
+
120
+
For production deployment (Chrome Web Store):
121
+
122
+
```bash
123
+
pnpm run build
124
+
cd dist/chrome
125
+
zip -r ../chrome.zip .
126
+
```
127
+
128
+
Upload `dist/chrome.zip` to Chrome Web Store.
129
+
130
+
## Architecture
131
+
132
+
- **Content Script** (`src/content/index.ts`) - Runs on x.com, detects page, scrapes usernames
133
+
- **Background Worker** (`src/background/service-worker.ts`) - Manages state, coordinates messaging
134
+
- **Popup UI** (`src/popup/`) - User interface when clicking extension icon
135
+
- **Scrapers** (`src/content/scrapers/`) - Platform-specific scraping logic (Twitter, future: Threads, etc.)
136
+
- **Messaging** (`src/lib/messaging.ts`) - Communication between components
137
+
- **API Client** (`src/lib/api-client.ts`) - Uploads data to ATlast API
138
+
139
+
## Future Enhancements
140
+
141
+
- Firefox support (Manifest V2/V3 compatibility)
142
+
- Threads.net scraper
143
+
- Instagram scraper
144
+
- TikTok scraper
145
+
- Auto-navigate to following page button
146
+
- Username detection from DOM
147
+
- Safari extension (via iOS app wrapper)