Export your Twitter/X's following/followers list to a CSV/JSON/HTML file.
// ==UserScript==
// @name Export Twitter Following List
// @namespace https://github.com/prinsss/
// @version 1.0.0
// @description Export your Twitter/X's following/followers list to a CSV/JSON/HTML file.
// @author prin
// @match *://twitter.com/*
// @icon https://www.google.com/s2/favicons?sz=64&domain=twitter.com
// @grant unsafeWindow
// @run-at document-start
// @supportURL https://github.com/prinsss/export-twitter-following-list/issues
// @license MIT
// ==/UserScript==
(function () {
'use strict';
/*
|--------------------------------------------------------------------------
| Global Variables
|--------------------------------------------------------------------------
*/
const SCRIPT_NAME = 'export-twitter-following-list';
/** @type {Element} */
let panelDom = null;
/** @type {Element} */
let listContainerDom = null;
/** @type {IDBDatabase} */
let db = null;
let isList = false;
let savedCount = 0;
let targetUser = '';
let currentType = '';
let previousPathname = '';
const infoLogs = [];
const errorLogs = [];
const buffer = new Set();
const currentList = new Map();
const currentListSwapped = new Map();
const currentListUniqueSet = new Set();
/*
|--------------------------------------------------------------------------
| Script Bootstraper
|--------------------------------------------------------------------------
*/
initDatabase();
hookIntoXHR();
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', onPageLoaded);
} else {
onPageLoaded();
}
// Determine wether the script should be run.
function bootstrap() {
const pathname = location.pathname;
if (pathname === previousPathname) {
return;
}
previousPathname = pathname;
// Show the script UI on these pages:
// - User's following list
// - User's followers list
// - List's member list
// - List's followers list
const listRegex = /^\/i\/lists\/(.+)\/(followers|members)/;
const userRegex = /^\/(.+)\/(following|followers_you_follow|followers|verified_followers)/;
isList = listRegex.test(pathname);
const isUser = userRegex.test(pathname);
if (!isList && !isUser) {
destroyControlPanel();
return;
}
const regex = isList ? listRegex : userRegex;
const parsed = regex.exec(pathname) || [];
const [match, target, type] = parsed;
initControlPanel();
updateControlPanel({ type, username: isList ? `list_${target}` : target });
}
// Listen to URL changes.
function onPageLoaded() {
new MutationObserver(bootstrap).observe(document.head, {
childList: true,
});
info('Script ready.');
}
/*
|--------------------------------------------------------------------------
| Page Scroll Listener
|--------------------------------------------------------------------------
*/
// When the content of the list changes, we extract some information from the DOM.
// Note that Twitter is using Virtual List so DOM nodes are always recycled.
function onListChange() {
listContainerDom.childNodes.forEach((child) => {
// NOTE: This may vary as Twitter upgrades.
const link = child.querySelector(
'div[role=button] > div:first-child > div:nth-child(2) > div:first-child ' +
'> div:first-child > div:first-child > div:nth-child(2) a'
);
if (!link) {
debug('No link element found in list child', child);
return;
}
const span = link.querySelector('span');
const parsed = /@(\w+)/.exec(span.textContent) || [];
const [match, username] = parsed;
if (!username) {
debug('No username found in the link', span.textContent, child);
return;
}
// We use a emoji to mark that a user was added into current exporting list.
const mark = ' ✅';
if (currentListUniqueSet.has(username)) {
// When you scroll back, the DOM was reset so we need to mark it again.
if (!span.textContent.includes(mark)) {
const index = currentListSwapped.get(username);
span.innerHTML += `${mark}😸 (${index})`;
}
return;
}
savedCount += 1;
updateControlPanel({ count: savedCount });
// Add the username extracted to the exporting list.
const index = savedCount;
currentListUniqueSet.add(username);
currentList.set(index, username);
currentListSwapped.set(username, index);
span.innerHTML += `${mark} (${index})`;
});
}
function attachToListContainer() {
// NOTE: This may vary as Twitter upgrades.
if (isList) {
listContainerDom = document.querySelector(
'div[role="group"] div[role="dialog"] section[role="region"] > div > div'
);
} else {
listContainerDom = document.querySelector(
'main[role="main"] div[data-testid="primaryColumn"] section[role="region"] > div > div'
);
}
if (!listContainerDom) {
error(
'No list container found. ' +
'This may be a problem caused by Twitter updates. Please file an issue on GitHub: ' +
'https://github.com/prinsss/export-twitter-following-list/issues'
);
return;
}
// Add a border to the attached list container as an indicator.
listContainerDom.style.border = '2px dashed #1d9bf0';
// Listen to the change of the list.
onListChange();
new MutationObserver(onListChange).observe(listContainerDom, {
childList: true,
});
}
/*
|--------------------------------------------------------------------------
| User Interfaces
|--------------------------------------------------------------------------
*/
// Hide the script UI and clear all the cache.
function destroyControlPanel() {
document.getElementById(`${SCRIPT_NAME}-panel`)?.remove();
document.getElementById(`${SCRIPT_NAME}-panel-style`)?.remove();
panelDom = null;
listContainerDom = null;
currentType = '';
targetUser = '';
savedCount = 0;
currentList.clear();
currentListUniqueSet.clear();
currentListSwapped.clear();
}
// Update the script UI.
function updateControlPanel({ type, username, count = 0 }) {
if (!panelDom) {
error('Monitor panel is not initialized');
return;
}
if (type) {
currentType = type;
panelDom.querySelector('#list-type').textContent = type;
}
if (count) {
panelDom.querySelector('#saved-count').textContent = count;
}
if (username) {
targetUser = username;
panelDom.querySelector('#target-user').textContent = username;
}
}
// Show the script UI.
function initControlPanel() {
destroyControlPanel();
const panel = document.createElement('div');
panelDom = panel;
panel.id = `${SCRIPT_NAME}-panel`;
panel.innerHTML = `
<div class="status">
<p>List type: "<span id="list-type">following</span>"</p>
<p>Target user/list: @<span id="target-user">???</span></p>
<p>Saved count: <span id="saved-count">0</span></p>
</div>
<div class="btn-group">
<button id="export-start">START</button>
<button id="export-preview">PREVIEW</button>
<button id="export-dismiss">DISMISS</button>
<button id="export-csv">Export as CSV</button>
<button id="export-json">Export as JSON</button>
<button id="export-html">Export as HTML</button>
<button id="dump-database">Dump Database</button>
</div>
<pre id="export-logs" class="logs"></pre>
<pre id="export-errors" class="logs"></pre>
`;
const style = document.createElement('style');
style.id = `${SCRIPT_NAME}-panel-style`;
style.innerHTML = `
#${SCRIPT_NAME}-panel {
position: fixed;
top: 30px;
left: 30px;
padding: 10px;
background-color: #f7f9f9;
border: 1px solid #bfbfbf;
border-radius: 16px;
box-shadow: rgba(0, 0, 0, 0.08) 0px 8px 28px;
width: 300px;
line-height: 2;
}
#${SCRIPT_NAME}-panel .logs {
text-wrap: wrap;
line-height: 1;
font-size: 12px;
max-height: 300px;
overflow-y: scroll;
}
#${SCRIPT_NAME}-panel p { margin: 0; }
#${SCRIPT_NAME}-panel .btn-group { display: flex; flex-direction: row; flex-wrap: wrap; }
#${SCRIPT_NAME}-panel button { margin-top: 3px; margin-right: 3px; }
#${SCRIPT_NAME}-panel #export-errors { color: #f4212e; }
`;
document.body.appendChild(panel);
document.head.appendChild(style);
panel.querySelector('#export-start').addEventListener('click', onExportStart);
panel.querySelector('#export-preview').addEventListener('click', onExportPreview);
panel.querySelector('#export-dismiss').addEventListener('click', onExportDismiss);
panel.querySelector('#export-csv').addEventListener('click', onExportCSV);
panel.querySelector('#export-json').addEventListener('click', onExportJSON);
panel.querySelector('#export-html').addEventListener('click', onExportHTML);
panel.querySelector('#dump-database').addEventListener('click', onDumpDatabase);
}
// The preview modal.
function openPreviewModal() {
const modal = document.createElement('div');
modal.id = `${SCRIPT_NAME}-modal`;
modal.innerHTML = `
<div class="modal-content">
<button id="modal-dismiss">X</button>
<div id="preview-table-wrapper">
<p>Loading...</p>
</div>
</div>
`;
const style = document.createElement('style');
style.id = `${SCRIPT_NAME}-modal-style`;
style.innerHTML = `
#${SCRIPT_NAME}-modal {
position: fixed;
top: 0;
left: 0;
width: 100vw;
height: 100vh;
background: rgba(0, 0, 0, 0.4);
display: flex;
align-items: center;
justify-content: center;
}
#${SCRIPT_NAME}-modal .modal-content {
position: relative;
width: 800px;
height: 600px;
background-color: #f7f9f9;
border-radius: 16px;
padding: 16px;
}
#${SCRIPT_NAME}-modal #modal-dismiss {
position: absolute;
top: 10px;
right: 10px;
}
#${SCRIPT_NAME}-modal #preview-table-wrapper {
width: 100%;
height: 100%;
overflow: scroll;
}
#${SCRIPT_NAME}-modal table {
border-collapse: collapse;
border: 2px solid #c8c8c8;
}
#${SCRIPT_NAME}-modal td,
#${SCRIPT_NAME}-modal th {
border: 1px solid #bebebe;
padding: 5px 10px;
}
`;
document.body.appendChild(modal);
document.head.appendChild(style);
modal.querySelector('#modal-dismiss').addEventListener('click', () => {
document.body.removeChild(modal);
document.head.removeChild(style);
});
const wrapper = modal.querySelector('#preview-table-wrapper');
exportToHTMLFormat().then((html) => {
wrapper.innerHTML = html;
});
}
/*
|--------------------------------------------------------------------------
| Exporters
|--------------------------------------------------------------------------
*/
async function exportToCSVFormat() {
const list = await getDetailedCurrentList();
const array = [...list.values()];
const header = 'number,name,screen_name,profile_image,following,followed_by,description,extra';
const rows = array
.map((value, key) => [
String(key),
value?.legacy?.name,
value?.legacy?.screen_name,
value?.legacy?.profile_image_url_https,
value?.legacy?.following ? 'true' : 'false',
value?.legacy?.followed_by ? 'true' : 'false',
sanitizeProfileDescription(
value?.legacy?.description,
value?.legacy?.entities?.description?.urls
),
JSON.stringify(value),
])
.map((item) => item.map((cell) => csvEscapeStr(cell)).join(','));
const body = rows.join('\n');
return header + '\n' + body;
}
async function exportToJSONFormat() {
const list = await getDetailedCurrentList();
const array = [...list.values()];
return JSON.stringify(array, undefined, ' ');
}
async function exportToHTMLFormat() {
const list = await getDetailedCurrentList();
const table = document.createElement('table');
table.innerHTML = `
<thead>
<tr>
<th>#</th>
<th>name</th>
<th>screen_name</th>
<th>profile_image</th>
<th>following</th>
<th>followed_by</th>
<th>description</th>
<th>extra</th>
</tr>
</thead>
`;
const tableBody = document.createElement('tbody');
table.appendChild(tableBody);
list.forEach((value, key) => {
const column = document.createElement('tr');
column.innerHTML = `
<td>${key}</td>
<td>${value?.legacy?.name}</td>
<td>
<a href="https://twitter.com/${value?.legacy?.screen_name}" target="_blank">
${value?.legacy?.screen_name}
</a>
</td>
<td><img src="${value?.legacy?.profile_image_url_https}"></td>
<td>${value?.legacy?.following ? 'true' : 'false'}</td>
<td>${value?.legacy?.followed_by ? 'true' : 'false'}</td>
<td>${sanitizeProfileDescription(
value?.legacy?.description,
value?.legacy?.entities?.description?.urls
)}</td>
<td>
<details>
<summary>Expand</summary>
<pre>${JSON.stringify(value)}</pre>
</details>
</td>
`;
tableBody.appendChild(column);
});
return table.outerHTML;
}
/*
|--------------------------------------------------------------------------
| Button Events
|--------------------------------------------------------------------------
*/
function onExportStart() {
info('Start listening on page scroll...');
attachToListContainer();
info('Scroll down the page and the list content will be saved automatically as you scroll.');
info('Tips: Do not scroll too fast since the list is lazy-loaded.');
}
function onExportDismiss() {
destroyControlPanel();
}
function onExportPreview() {
openPreviewModal();
}
async function onExportCSV() {
try {
const filename = `twitter-${targetUser}-${currentType}-${Date.now()}.csv`;
info('Exporting to CSV file: ' + filename);
const content = await exportToCSVFormat();
saveFile(filename, content);
} catch (err) {
error(err.message, err);
}
}
async function onExportJSON() {
try {
const filename = `twitter-${targetUser}-${currentType}-${Date.now()}.json`;
info('Exporting to JSON file: ' + filename);
const content = await exportToJSONFormat();
saveFile(filename, content);
} catch (err) {
error(err.message, err);
}
}
async function onExportHTML() {
try {
const filename = `twitter-${targetUser}-${currentType}-${Date.now()}.html`;
info('Exporting to HTML file: ' + filename);
const content = await exportToHTMLFormat();
saveFile(filename, content);
} catch (err) {
error(err.message, err);
}
}
async function onDumpDatabase() {
try {
const filename = `${SCRIPT_NAME}-database-dump-${Date.now()}.json`;
info('Exporting IndexedDB to file: ' + filename);
const obj = await dumpDatabase();
saveFile(filename, JSON.stringify(obj, undefined, ' '));
} catch (err) {
error(err.message, err);
}
}
/*
|--------------------------------------------------------------------------
| Database Management
|--------------------------------------------------------------------------
*/
function initDatabase() {
const request = indexedDB.open(SCRIPT_NAME, 1);
request.onerror = (event) => {
error('Failed to open database.', event);
};
request.onsuccess = () => {
db = request.result;
info('New connection to IndexedDB opened.');
// Flush buffer if there is any incoming data received before the DB is ready.
if (buffer.size) {
insertUserDataIntoDatabase([]);
}
};
request.onupgradeneeded = (event) => {
db = event.target.result;
info('New IndexedDB initialized.');
// Use the numeric user ID as primary key and the username as index for lookup.
const objectStore = db.createObjectStore('users', { keyPath: 'rest_id' });
objectStore.createIndex('screen_name', 'legacy.screen_name', { unique: false });
if (buffer.size) {
insertUserDataIntoDatabase([]);
}
};
}
function insertUserDataIntoDatabase(users) {
// Add incoming data to a buffer queue.
users.forEach((user) => buffer.add(user));
// If the DB is not ready yet at this point, queue the data and wait for it.
if (!db) {
info(`Added ${users.length} users to buffer`);
if (buffer.size > 100) {
error('The database is not initialized.');
error('Maximum buffer size exceeded. Current: ' + buffer.size);
}
return;
}
const toBeInserted = [...buffer.values()];
const insertLength = toBeInserted.length;
const transaction = db.transaction('users', 'readwrite');
const objectStore = transaction.objectStore('users');
transaction.oncomplete = () => {
info(`Added ${insertLength} users to database.`);
for (const item of toBeInserted) {
buffer.delete(item);
}
};
transaction.onerror = (event) => {
error(`Failed to add ${insertLength} users to database.`, event);
};
// Insert or update the user data.
toBeInserted.forEach((user) => {
const request = objectStore.put(user);
request.onerror = function (event) {
error(`Failed to write database. User ID: ${user.id}`, event, user);
};
});
}
// Get a user's record from database by his username.
async function queryDatabaseByUsername(username) {
if (!db) {
error('The database is not initialized.');
return;
}
const transaction = db.transaction('users', 'readonly');
const objectStore = transaction.objectStore('users');
// Use the defined index to look up.
const index = objectStore.index('screen_name');
const request = index.get(username);
return new Promise((resolve) => {
request.onsuccess = () => {
resolve(request.result);
};
request.onerror = (event) => {
error(`Failed to query user ${username} from database.`, event);
resolve(null);
};
});
}
// Takes a list of usernames and returns a list of user data, with original order preserved.
async function getDetailedCurrentList() {
const keys = currentList.keys();
const sortedKeys = [...keys].sort((a, b) => a - b);
const sortedDetailedList = new Map();
const promises = sortedKeys.map(async (key) => {
const username = currentList.get(key);
const res = await queryDatabaseByUsername(username);
sortedDetailedList.set(key, res);
});
await Promise.all(promises);
return sortedDetailedList;
}
// Get a user's record from database by his username.
async function dumpDatabase() {
if (!db) {
error('The database is not initialized.');
return;
}
const transaction = db.transaction('users', 'readonly');
const objectStore = transaction.objectStore('users');
const request = objectStore.openCursor();
const records = new Map();
return new Promise((resolve) => {
request.onsuccess = (event) => {
const cursor = event.target.result;
if (cursor) {
records.set(cursor.value.rest_id, cursor.value);
cursor.continue();
} else {
// No more results.
resolve(Object.fromEntries(records.entries()));
}
};
request.onerror = (event) => {
error(`Failed to query user ${username} from database.`, event);
resolve(null);
};
});
}
/*
|--------------------------------------------------------------------------
| Twitter API Hooks
|--------------------------------------------------------------------------
*/
// Here we hooks the browser's XHR method to intercept Twitter's Web API calls.
// This need to be done before any XHR request is made.
function hookIntoXHR() {
const originalOpen = unsafeWindow.XMLHttpRequest.prototype.open;
unsafeWindow.XMLHttpRequest.prototype.open = function () {
const url = arguments[1];
// NOTE: This may vary as Twitter upgrades.
// https://twitter.com/i/api/graphql/rRXFSG5vR6drKr5M37YOTw/Followers
if (/api\/graphql\/.+\/Followers/.test(url)) {
this.addEventListener('load', function () {
parseTwitterAPIResponse(
this.responseText,
(json) => json.data.user.result.timeline.timeline.instructions
);
});
}
// https://twitter.com/i/api/graphql/kXi37EbqWokFUNypPHhQDQ/BlueVerifiedFollowers
if (/api\/graphql\/.+\/BlueVerifiedFollowers/.test(url)) {
this.addEventListener('load', function () {
parseTwitterAPIResponse(
this.responseText,
(json) => json.data.user.result.timeline.timeline.instructions
);
});
}
// https://twitter.com/i/api/graphql/iSicc7LrzWGBgDPL0tM_TQ/Following
if (/api\/graphql\/.+\/Following/.test(url)) {
this.addEventListener('load', function () {
parseTwitterAPIResponse(
this.responseText,
(json) => json.data.user.result.timeline.timeline.instructions
);
});
}
// https://twitter.com/i/api/graphql/-5VwQkb7axZIxFkFS44iWw/ListMembers
if (/api\/graphql\/.+\/ListMembers/.test(url)) {
this.addEventListener('load', function () {
parseTwitterAPIResponse(
this.responseText,
(json) => json.data.list.members_timeline.timeline.instructions
);
});
}
// https://twitter.com/i/api/graphql/B9F2680qyuI6keStbcgv6w/ListSubscribers
if (/api\/graphql\/.+\/ListSubscribers/.test(url)) {
this.addEventListener('load', function () {
parseTwitterAPIResponse(
this.responseText,
(json) => json.data.list.subscribers_timeline.timeline.instructions
);
});
}
originalOpen.apply(this, arguments);
};
info('Hooked into XMLHttpRequest.');
}
// We parse the users' information in the API response and write them to the local database.
// The browser's IndexedDB is used to store the data persistently.
function parseTwitterAPIResponse(text, extractor) {
try {
const json = JSON.parse(text);
// NOTE: This may vary as Twitter upgrades.
const instructions = extractor(json);
const entries = instructions.find((item) => item.type === 'TimelineAddEntries').entries;
const users = entries
.filter((item) => item.content.itemContent)
.map((item) => ({
...item.content.itemContent.user_results.result,
entryId: item.entryId,
sortIndex: item.sortIndex,
}));
insertUserDataIntoDatabase(users);
} catch (err) {
error(
`Failed to parse API response. (Message: ${err.message}) ` +
'This may be a problem caused by Twitter updates. Please file an issue on GitHub: ' +
'https://github.com/prinsss/export-twitter-following-list/issues'
);
}
}
/*
|--------------------------------------------------------------------------
| Utility Functions
|--------------------------------------------------------------------------
*/
// Escape characters for CSV file.
function csvEscapeStr(s) {
return `"${s.replace(/\"/g, '""').replace(/\n/g, '\\n').replace(/\r/g, '\\r')}"`;
}
// Save a text file to disk.
function saveFile(filename, content) {
const link = document.createElement('a');
link.style = 'display: none';
document.body.appendChild(link);
const blob = new Blob([content], { type: 'text/plain' });
const url = URL.createObjectURL(blob);
link.href = url;
link.download = filename;
link.click();
URL.revokeObjectURL(url);
}
// Replace any https://t.co/ link in the string with its corresponding real URL.
function sanitizeProfileDescription(description, urls) {
let str = description;
if (urls?.length) {
for (const { url, expanded_url } of urls) {
str = str.replace(url, expanded_url);
}
}
return str;
}
// Show info logs on both screen and console.
function info(line, ...args) {
console.info('[Export Twitter Following List]', line, ...args);
infoLogs.push(line);
const dom = panelDom ? panelDom.querySelector('#export-logs') : null;
if (dom) {
dom.innerHTML = infoLogs.map((content) => '> ' + String(content)).join('\n');
}
}
// Show error logs on both screen and console.
function error(line, ...args) {
console.error('[Export Twitter Following List]', line, ...args);
errorLogs.push(line);
const dom = panelDom ? panelDom.querySelector('#export-errors') : null;
if (dom) {
dom.innerHTML = errorLogs.map((content) => '> ' + String(content)).join('\n');
}
}
// Show debug logs on console.
function debug(...args) {
console.debug('[Export Twitter Following List]', ...args);
}
})();