twitter-api-v2

What is twitter-api-v2?

The twitter-api-v2 npm package is a comprehensive library for interacting with the Twitter API v2. It allows developers to perform a wide range of actions such as posting tweets, retrieving user information, managing direct messages, and more. The package is designed to be easy to use and supports both REST and streaming APIs.

What are twitter-api-v2's main functionalities?

Posting a Tweet

This feature allows you to post a tweet to your Twitter account. The code sample demonstrates how to initialize the TwitterApi client with an access token and post a tweet saying 'Hello, world!'.

const { TwitterApi } = require('twitter-api-v2');
const client = new TwitterApi('YOUR_ACCESS_TOKEN');

async function postTweet() {
  const tweet = await client.v2.tweet('Hello, world!');
  console.log(tweet);
}

postTweet();

Fetching User Information

This feature allows you to fetch information about a specific Twitter user by their username. The code sample shows how to retrieve and log the user information for the 'TwitterDev' account.

const { TwitterApi } = require('twitter-api-v2');
const client = new TwitterApi('YOUR_ACCESS_TOKEN');

async function getUserInfo() {
  const user = await client.v2.userByUsername('TwitterDev');
  console.log(user);
}

getUserInfo();

Streaming Tweets

This feature allows you to stream tweets in real-time based on certain criteria. The code sample demonstrates how to set up a stream to listen for tweets and log the tweet data as it comes in.

const { TwitterApi } = require('twitter-api-v2');
const client = new TwitterApi('YOUR_ACCESS_TOKEN');

async function streamTweets() {
  const stream = await client.v2.searchStream({ 'tweet.fields': ['author_id'] });
  for await (const { data } of stream) {
    console.log(data);
  }
}

streamTweets();

Other packages similar to twitter-api-v2

twit

The 'twit' package is another popular library for interacting with the Twitter API. It supports both REST and streaming APIs, similar to twitter-api-v2. However, 'twit' is designed for the older Twitter API v1.1, whereas twitter-api-v2 is specifically for the newer API v2.

twitter-lite

The 'twitter-lite' package is a lightweight alternative for interacting with the Twitter API. It supports both REST and streaming APIs and is designed to be minimalistic and efficient. While it can be used with both API v1.1 and v2, it may lack some of the more advanced features and ease of use provided by twitter-api-v2.

node-twitter-api

The 'node-twitter-api' package provides a simple interface for interacting with the Twitter API. It supports basic functionalities such as posting tweets and fetching user information. However, it is less comprehensive and may not support all the features available in twitter-api-v2.

README

Twitter API v2

Strongly typed, full-featured, light, versatile yet powerful Twitter API v1.1 and v2 client for Node.js.

Highlights

✅ Ready for v2 and good ol' v1.1 Twitter API

✅ Light: No dependencies, 11.7kb minified+gzipped

✅ Bundled types for request parameters and responses

✅ Streaming support

✅ Pagination utils

✅ Media upload helpers

Why?

Sometimes, you just want to quickly bootstrap an application using the Twitter API. Even if they're a lot a available librairies on the JavaScript ecosystem, they usually just provide wrappers around HTTP methods, and some of them are bloated with many dependencies.

twitter-api-v2 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 comparaison with other libs:

Package	API version(s)	Response typings	Media helpers	Pagination	Subdependencies	Size (gzip)
twitter-api-v2	v1.1, v2, labs	✅	✅	✅	0	~11.7 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

*No support for media/upload, cannot send a multipart/form-data encoded-body without tricks

Features

Here's the detailed feature list of twitter-api-v2:

Basics:

• Support for v1.1 and v2 of Twitter API
• Make signed HTTP requests to Twitter with every Twitter required auth type:
  • classic OAuth 1.0a authentification for user-context endpoints
  • OAuth2 Bearer token for app-only endpoints
  • Basic HTTP Authorization, required for some auth endpoints or Entreprise API
• Helpers for numerous HTTP request methods (GET, POST, PUT, DELETE and PATCH), 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

Request helpers:

• 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 will be a breeze
• 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 (WIP - not all public endpoints are available)
• Bundled parsing of rate limit headers
• Typed errors, meaningful error messages, error enumerations for both v1.1 and v2

Type-safe first:

• Typings for tweet, user, media entities (and more) are bundled in this package!
• 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.

How to use

Install it through your favorite package manager:

yarn add twitter-api-v2
# or
npm i twitter-api-v2

Here's is a quick example of usage:

import TwitterApi from 'twitter-api-v2';

// Instanciate 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 roClient = twitterClient.readOnly;

// Play with the built in methods
const user = await roClient.v2.userByUsername('plhery');
await twitterClient.v1.tweet('Hello, this is a test.');
// You can upload media easily!
await twitterClient.v1.uploadMedia('./big-buck-bunny.mp4');

// Or manually call the API
await twitterClient.v2.get('tweets/search/recent', { query: 'nodeJS', max_results: 100 });
const tweets = await twitterClient.get('https://api.twitter.com/2/tweets/search/recent?query=nodeJS&max_results=100');

Note: Top-level use of await is not available in most of Node.js usage. You might need to wrap awaits into async functions. See MDN related documentation.

Basics

You want to know more about client usage? See the Basics!

Examples

Wanna see that in action? Jump to Examples part.

Authentification

Lost between the different ways to auth inside Twitter API? Don't know how to implement 3-legged OAuth flow?

See Authentification part to know more and have a comprehensive guide a every Twitter authentification process.

Streaming

APIs dedicated to streaming are available in Streaming part.

Full package API

Each Twitter endpoint > method association is described in details inside the v1.1 comprehensive documentation and the v2 comprehensive documentation.