A simple wrapper library around the Twitter Syndication API. Inspired by: https://github.com/zedeus/nitter/issues/919#issuecomment-1616703690

About

The Syndication API is what is used by embedded widgets and its ease-of-use brings some notable limitations. Twittxr is best suited for setting up a user feed or getting a single tweet, it will not replace a fully fledged scraper/client.

✅ Features

• Can include retweets and/or replies by the user.
• Option to pass cookie object or string to get Sensitive/NSFW Tweets.
• Ability to pass a Puppeteer page, bypassing potential API auth issues.
• Fast response times thanks to Undici.
• Intuitive syntax and included type definitions.

❌ Limitations

• When getting a Timeline, only up to 100 Tweets can be returned. (May be 20 in some cases)

Authentication

Twitter is now known to require a cookie to return any data! I strongly advise you pass the cookie parameter in all of your requests.

How do I get my session cookie?

1. Click here -> Right click -> Inspect Element

2. Under 'Network' find the request with the document type.

3. Find the header with the key Cookie and copy the whole string.

4. Store this in an .env file like so:

   TWITTER_COOKIE="yourCookieStringHere"

Installation

bun add twittxr

Optionally, you can install puppeteer >=16 to use as a fallback on failed requests. This will avoid issues with Cloudflare, e.g. "403 Forbidden".

bun add twittxr puppeteer

Usage

import { Timeline, Tweet } from 'twittxr' // ESM
const { Timeline, Tweet } = require('twittxr') // CommonJS

Get a single Tweet

// Does not return the same type as Timeline.get()
const tweet = await Tweet.get('1674865731136020505')

Get a user Timeline

// The retweets and replies default to false.
const timelineWithRts = await Timeline.get('elonmusk', { 
  cookie: process.env.TWITTER_COOKIE,
  retweets: true,
  replies: false, // This is the user's replies, not replies to their Tweets.
})

Using Puppeteer

Note By default, Puppeteer will be used as a fallback for failed requests - if installed. However, it is possible to solely use Puppeteer by calling await usePuppeteer().

import { Timeline } from 'twittxr'

// Launches a basic headless browser & automatically closes the page.
await Timeline.usePuppeteer()
const tweets = await Timeline.get('elonmusk', { 
  cookie: process.env.TWITTER_COOKIE
})

const puppeteer = require('puppeteer-extra')

// Use plugins if desired
puppeteer.use(ExamplePlugin())

const browser = await puppeteer.launch({ headless: true })

// Creates a new page and closes it automatically after every .get() call
await Timeline.usePuppeteer({ browser, autoClose: true })
const tweets = await Timeline.get('elonmusk', { 
  cookie: process.env.TWITTER_COOKIE
})

const puppeteer = require('puppeteer')
const browser = await puppeteer.launch({ headless: true })
const page = await browser.newPage()

// Pass the page, but do not automatically close it.
await Timeline.usePuppeteer({ page, autoClose: false })
const tweets = await Timeline.get('elonmusk', { 
  cookie: process.env.TWITTER_COOKIE
})

await page.goto('https://google.com') // Continue to manipulate the page.
await page.close() // Close the page manually.

To stop using Puppeteer at any point, you can simply call:

Timeline.disablePuppeteer()

Disclaimer

You must use this library at your own discretion!

I will not be held accountable for any outcomes that may result from its usage, including and not limited to:

• Banning/Suspension of your Twitter account.
• Lawsuits, fines and other Twitter related legal disputes.
• Hacking of network and/or account when providing a proxy or exposing cookies.