The dfuse team is proud to announce the release of our revamped dfuse Client library for JavaScript/TypeScript projects. The new library is now the de-facto standard to interface with both the dfuse Stream API and the dfuse REST API when using JavaScript/TypeScript.

Available under the new package @dfuse/client, we have provided full documentation, getting started tutorials, and a full suite of basic and advanced examples.

This new library replaces our previous interface library @dfuse/eosws-js. It has many additions that are definitely worth switching over for. To ease this process, we have written a migration guide to walk you through this step-by-step. The new library also includes new boilerplate code that is now within the library directly.

Here is an overview of some of the changes included in this new library.

Automatic API Key Management

The new library is now fully aware of our new authentication mechanism based on a long-lived API key and issuance of short-lived API token (JWT) to interact with the dfuse API. For more information on this, be sure to read through our documents concerning our authentication protocol.

The library now accepts an API key and will fully automate the rotation of the generated short-lived API tokens: freshness, expiration and persistence.

The library also has sane defaults out of the box for API token persistence. On a browser environment, we store the API token in localStorage in the browser. In a Node.js environment, the API token is stored by default in a file at ~/.dfuse/<sha256-api-key>/token.json.

By using the latest library, you can forget about having to deal with API tokens altogether. Let dfuse handle it for you!

Stream Re-connection & Stream Restart

The new library improves the dfuse Stream API interaction by making it much easier for the developer. Foremost, the library now handles automatic connection/disconnection of the underlying WebSocket. When starting a stream, the library automatically connects the WebSocket. When you close all active streams, the connection is automatically disconnected.

The new library also greatly improves the workflow for re-connection of a WebSocket. A stream can now be marked to track your progression with ease, and the library will automatically restart the stream at the last marked point once the connection is reestablished. This is all done automatically, you simply need to mark your stream at a regular interval to pick up exactly where you left off.

const stream = client.streamActionTraces(..., () => {
stream.mark({{ atBlockNum: blockNum }})

Using this simple example above, you can easily mark your progress. Check the advanced example for never missing a beat for a more complete code sample, as well be sure to read through our documentation which goes more in-depth.

Note The stream’s marker is held in-memory; you are still responsible for making it persistent across a process restart in your own code.


The new library also supports the full dfuse REST API, closing the gap with our previous library. All REST calls can be done using the dfuse Client instance.

If you were previously using EOS Nation library, you should also migrate to @dfuse/client, as the new library fully incorporates all features. A major thank you to EOS Nation and EOS Cafe Block for providing the initial implementation.

Tooling, Documentation & Examples

We now provide a UMD build which is also served by the CDN, enabling you to use the dfuse Client without a bundling library like Webpack or Rollup. Visit our GitHub repository for a browser-only example.

The now-deprecated eos-ws.js library distribution contained only a few examples, which is something we were happy to improve upon. The new library distribution contains a full-blown list of new and advanced examples to efficiently deal with all aspects of a blockchain project and the dfuse API. Refer to the documentation section Examples for the complete list of examples included in the library.

We now also have a React example app using the @dfuse/client package to interact with the dfuse Stream API. The full source code of the application is available for your perusal.

You should also review src/App.js which contains the full source code of the example. The other files are support and styling files. Thanks to the new API reference material generated straight from the source files, the library usage is now also much easier to discover. Here’s a quick list of the important API reference material for the library.

Any feedback or comments? Please connect with us through our Telegram channel and let us know what you’re up to!