TypeScript icon, indicating that this package has built-in type declarations

    1.6.0 • Public • Published

    Twitter API v2

    Twitter API v2 badge Twitter API v1.1 badge Version badge Checks badge Package size badge

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


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

    Light: No dependencies, 16kb minified+gzipped

    Bundled types for request parameters and responses

    Streaming support

    Pagination utils

    Media upload helpers


    Sometimes, you just want to quickly bootstrap an application using the Twitter API. Even if they're a lot of available libraries 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 Subdeps Size (gzip) Install size
    twitter-api-v2 v1.1, v2, labs 0 ~16 kB twitter-api-v2 install size badge
    twit v1.1 51 ~214.5 kB twit install size badge
    twitter v1.1 50 ~182.1 kB twitter install size badge
    twitter-lite v1.1, v2 * 4 ~5.3 kB twitter-lite install size badge
    twitter-v2 v2 7 ~4.5 kB twitter-v2 install size badge

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


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


    • Support for v1.1 and v2 of Twitter API
    • Make signed HTTP requests to Twitter with every auth type: OAuth 1.0a, OAuth2 and Basic HTTP Authorization
    • 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
    • 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!
    • 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');


    Learn how to use the full potential of twitter-api-v2.


    npm i twitter-api-v2

    DownloadsWeekly Downloads






    Unpacked Size

    390 kB

    Total Files


    Last publish


    • phery