Strongly typed, full-featured, light, versatile yet powerful Twitter API v1.1 and v2 client for Node.js.
Former main contributor: @alkihis
We are disappointed and discouraged by the recent turn of events at Twitter since the takeover by Elon Musk. We are saddened to see that much of the hard work of the past few years on the API, led by an amazing team including @andypiper, has been shelved.
✅ Ready for v2 and good ol' v1.1 Twitter API ✅ Light: No dependencies, 23kb minified+gzipped ✅ Bundled types for request parameters and responses ✅ Streaming support ✅ Pagination utils ✅ User-context authentication with OAuth2 ✅ Media upload helpers
Install it through your favorite package manager:
yarn add twitter-api-v2
# or
npm i twitter-api-v2Here's a quick example of usage:
import { TwitterApi } from 'twitter-api-v2';
// Instantiate with desired auth type (here's Bearer v2 auth)
const twitterClient = new TwitterApi('<your_app_user_token>');
// Tell typescript it's a readonly app
const readOnlyClient = twitterClient.readOnly;
// Play with the built in methods
const user = await readOnlyClient.v2.userByUsername('plhery');
await twitterClient.v2.tweet('Hello, this is a test.');
// You can upload media easily!
await twitterClient.v1.uploadMedia('./big-buck-bunny.mp4');Sometimes, you just want to quickly bootstrap an application using the Twitter API. Even though there are a lot of libraries available on the JavaScript ecosystem, they usually just provide wrappers around HTTP methods, and some of them are bloated with many dependencies.
twitter-api-v2 is meant to provide full endpoint wrapping, from method name to response data,
using descriptive typings for read/write/DMs rights, request parameters and response payload.
A small feature comparison with other libs:
| Package | API version(s) | Response typings | Media helpers | Pagination | Subdeps | Size (gzip) | Install size |
| -------------- |---------------------| ---------------- | ------------- | ---------- | --------------- | -------------:| |
| twitter-api-v2 | v1.1, v2, labs, ads | ✅ | ✅ | ✅ | 0 | ~23 kB | |
| twit | v1.1 | ❌ | ✅ | ❌ | 51 | ~214.5 kB |
|
| twitter | v1.1 | ❌ | ❌ | ❌ | 50 | ~182.1 kB |
|
| twitter-lite | v1.1, v2 | ❌ | ❌ | ❌ | 4 | ~5.3 kB |
|
| twitter-v2 | v2 | ❌ | ❌ | ❌ | 7 | ~4.5 kB |
|
Here's everything twitter-api-v2 can do:
- Support for v1.1 and v2 of Twitter API
- Make signed HTTP requests to Twitter with every auth type: OAuth 1.0a, OAuth2 (even brand new user context OAuth2!) and Basic HTTP Authorization
- Helpers for numerous HTTP request methods (
GET,POST,PUT,DELETEandPATCH), that handle query string parse & format, automatic body formatting and more - High-class support for stream endpoints, with easy data consumption and auto-reconnect on stream errors
- Automatic paginator for endpoints like user and tweet timelines, allowing payload consumption with modern asynchronous iterators until your rate-limit is hit
- Convenient methods for authentication - generate auth links and ask for tokens to your users
- Media upload with API v1.1, including long video & subtitles support, automatic media type detection, chunked upload and support for concurrent uploads
- Dedicated methods that wraps API v1.1 & v2 endpoints, with typed arguments and fully typed responses
- Typed errors, meaningful error messages, error enumerations for both v1.1 and v2
- Typings for tweet, user, media entities (and more) are bundled!
- Type-safe wrapping of dedicated methods in 3 right level: DM/Read-write/Read-only (just like Twitter API do!) - you can declare a read-only client - you will only see the methods associated with read-only endpoints
And last but not least, fully powered by native Promises.
Learn how to use the full potential of twitter-api-v2.
- Get started
- Use endpoints wrappers — ensure typings of request & response
- Deep diving into requests
- Twitter Ads API (beta)
The cli-streamer.js tool enables you to stream tweets from the Twitter API v2 and export interactions as Gephi-compatible edge format for network visualization and analysis.
No additional dependencies needed! The CLI tool is included in the package.
node src/cli-streamer.js --bearer <YOUR_BEARER_TOKEN> --keywords "keyword1,keyword2" --output edges.csv--bearer(required): Your Twitter API v2 Bearer token--keywords(required): Comma-separated list of keywords to search for--output(optional): Output file path (default:twitter_edges.csv)
# Search for tweets about JavaScript and Node.js
node src/cli-streamer.js --bearer "AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHHIII" --keywords "JavaScript,Node.js" --output graph_edges.csvThe tool generates a CSV file compatible with Gephi with the following columns:
- Source: The tweet author ID
- Target: The mentioned user, hashtag, or URL
- Type: The type of interaction (mention, hashtag, url_reference)
- Weight: Edge weight (currently always 1)
- interaction_type: Duplicate of Type field for reference
Source,Target,Type,Weight,interaction_type
"123456789","@mention_user",mention,1,mention
"123456789","#JavaScript",hashtag,1,hashtag
"123456789","https://example.com",url_reference,1,url_reference- Open Gephi
- Go to File → Import Spreadsheet
- Select your generated CSV file
- Choose "Edges table" as the import type
- Ensure "Directed" is selected
- Click Import
- Your network graph is ready for visualization!
- Extracts mentions (@username mentions)
- Extracts hashtags (#hashtag references)
- Extracts URL references from tweets
- Batch processing for efficient handling of large datasets
- CSV format compatible with Gephi, Cytoscape, and other network analysis tools
Official plugins for twitter-api-v2:
@twitter-api-v2/plugin-token-refresher: Handle OAuth 2.0 (user-context) token refreshing for you@twitter-api-v2/plugin-rate-limit: Access and store automatically rate limit data@twitter-api-v2/plugin-cache-redis: Store responses in a Redis store and serve cached responses