twittxr

KO | EN

gitlite — search

#javascript #python #ai #golang #go #android #deep-learning #docker #nodejs #vue #pytorch #ios #mcp #openai

(★ 37)

Twitter/X Syndication API wrapper.

twittxr Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Twittxr <img align="left" width="132" height="132" src="./icon.png">

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

[![Codacy Badge](https://app.codacy.com/project/badge/Grade/3295160336cf41108ab4b409f6baf6c5)](https://app.codacy.com/gh/Owen3H/twittxr/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[![Build Status Badge](https://img.shields.io/github/actions/workflow/status/Owen3H/twittxr/main.yml)](https://github.com/Owen3H/twittxr/actions)
[![Discord](https://img.shields.io/discord/1215213004824645674?logo=discord&logoColor=white&color=blue)](https://discord.gg/64Vq7cpdGV)

## Overview
As you may know, Twitter/X ended free access to its API, making [IFTTT](https://ifttt.com) and other services obsolete for many users.
Instead, this wrapper aims to use the public facing [Syndication API](https://syndication.twitter.com/srv/timeline-profile/screen-name/elonmusk)
which is used by embedded widgets, though there are some notable limitations by using it as an "alternative".

**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](https://pptr.dev) page, bypassing potential API auth issues.
- Falls back to native `fetch` in the browser, allowing use outside of **Node**.
- 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)

## Installation
```console
bun add twittxr
```

Optionally, you can install `puppeteer` >=16 to use as a fallback on failed requests. 
This can potentially avoid issues with Cloudflare. Ex: "403 Forbidden".

```console
bun add twittxr puppeteer
```

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

***How do I get my session cookie?***
1. Login to Twitter -> Right click -> **Inspect Element**
2. Select the **Application** tab -> Refresh the page -> Find the **Cookies** section.
3. Note down the cookies labelled `guest_id`, `auth_token`, `ct0` and `kdt`.

Now you have two options to store and use these cookies.

<details>
 <summary>Option A - Building the string manually</summary>

Once you have your cookies, build a string in your `.env` file that follows the following format:

```bash
  TWITTER_COOKIE="guest_id=someValue; auth_token=someValue; ct0=someValue; kdt=someValue; dnt=1;"
  ```

This way we only store one single line in the file and the `dnt` (Do-Not-Track) cookie can be customised if desired.\
 Once complete, simply reference the cookie like so when passing it to methods requiring auth.
 ```ts
 const cookie = process.env.TWITTER_COOKIE
 ```
</details>

<details>
 <summary>Option B - Using <code>buildCookieString</code></summary>

This way is slightly more verbose and always includes a `dnt=1` cookie for you but requires you to use multiple lines in your `.env` file.

```bash
  GUEST_ID="someValue"
  AUTH_TOKEN="someValue"
  CT0="someValue"
  KDT="someValue"
  ```

We can then make use of the provided `buildCookieString` helper method before passing to methods requiring auth.
  ```ts
  import { buildCookieString } from "twittxr"

const cookie = buildCookieString({
 guest_id: process.env.GUEST_ID,
 auth_token: process.env.AUTH_TOKEN,
 ct0: process.env.CT0,
 kdt: process.env.KDT
 })
 ```
</details>

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

### Get a single Tweet
No auth required.
```ts
// Does not return the same type as Timeline.get()
const tweet = await Tweet.get(1674865731136020505) // Or string
```

### Get a user Timeline
See the **Authentication** section to obtain a cookie string.

```ts
// The retweets and replies default to false.
const timelineWithRts = await Timeline.get('elonmusk', { 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()`.

```ts
import { Timeline } from 'twittxr'
```

<details>
 <summary>No config</summary>

```ts
// Launches a basic headless browser & automatically closes the page.
await Timeline.usePuppeteer()
const tweets = await Timeline.get('elonmusk', { cookie })
```
</details>

<details>
 <summary>With custom browser</summary>

```ts
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 })
```
</details>

```js
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 })

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

To stop using Puppeteer at any point, you can simply call:
```js
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/X account.
- Lawsuits, fines and other Twitter/X related legal disputes.
- Hacking of network and/or account when providing a proxy or exposing cookies.

twittxr

twittxr Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

twittxr

twittxr Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README