Twitter V2 API for Node.js

An asynchronous client library for the Twitter REST and Streaming V2 API's.

Try it now

const Twitter = require('twitter-v2');

const client = new Twitter({
  consumer_key: '',
  consumer_secret: '',
  access_token_key: '',
  access_token_secret: '',
});

const { data } = await client.get('tweets', { ids: '1228393702244134912' });
console.log(data);

Installation

npm install twitter-v2

Quick Start

You will need valid Twitter developer credentials in the form of a set of consumer keys. You can get early access V2 keys here.

For user based authentication:

User authentication requires your app's consumer keys and access tokens obtained from oauth 1.0a.

const client = new Twitter({
  consumer_key: '',
  consumer_secret: '',
  access_token_key: '',
  access_token_secret: '',
});

For app based authentication:

Alternatively, app authentication (which can only access public data but is often suitable for server applications) only needs your app's consumer keys and/or bearer token.

const client = new Twitter({
  consumer_key: '',
  consumer_secret: '',
});

or

const client = new Twitter({
  bearer_token: '',
});

REST API

You can make GET, POST, and DELETE requests against the REST API via the convenience methods.

client.get(path, urlParams);
client.post(path, body, urlParams);
client.delete(path, urlParams);

The REST API convenience methods return Promises.

Streaming API

Use the streaming convenience methods for any stream APIs.

client.stream(path, urlParams);

The Streaming API will return an async iterator with the convenience method close(). Ensure that you call close() when done with a stream, otherwise it will continue to download content from Twitter in the background.

const stream = client.stream(path, urlParams);

// Close the stream after 30s.
setTimeout(() => {
  stream.close();
}, 30000);

for await (const { data } of stream) {
  console.log(data);
}

Note that reconnect logic is not handled by this package, you're responsible for implementing it based on the needs of your application. The stream will close itself in two cases:

1. If the stream becomes disconnected for an unknown reason, a TwitterError will be thrown.
2. If Twitter's backend disconnects the stream healthily, the stream will be closed with no error.

If you wish to continuously listen to a stream, you'll need to handle both of these cases. For example:

async function listenForever(streamFactory, dataConsumer) {
  try {
    for await (const { data } of streamFactory()) {
      dataConsumer(data);
    }
    // The stream has been closed by Twitter. It is usually safe to reconnect.
    console.log('Stream disconnected healthily. Reconnecting.');
    listenForever(streamFactory, dataConsumer);
  } catch (error) {
    // An error occurred so we reconnect to the stream. Note that we should
    // probably have retry logic here to prevent reconnection after a number of
    // closely timed failures (may indicate a problem that is not downstream).
    console.warn('Stream disconnected with error. Retrying.', error);
    listenForever(streamFactory, dataConsumer);
  }
}

listenForever(
  () => client.stream('tweets/search/stream'),
  (data) => console.log(data)
);

V1.1 API Support

This module does not support previous versions of the Twitter API, however it works well with the following V1.1 modules