Skip to content

JavaScript

The JS HTTP Client was designed to work in the browser, using Node.js, or in Electron.

To use the JS HTTP Client, you'll need either a locally running Daemon or a locally running Desktop Tray instance containing a Textile account and available on localhost with default ports for both the API and Gateway.

Installation

The JS HTTP Client is published as an NPM Package. You are free to use the source code directly or use a package manager to install the official release.

NPM

npm install @textile/js-http-client

Yarn

yarn add @textile/js-http-client

TypeScript

We strongly recommend using TypeScript if you plan to use the JS Client in your project. The JS Client's endpoints are all typed and those types are available to projects that support them. Because Textile libraries are rapidly developing, this will make your upgrade process much easier and faster.

If you don't normally use TypeScript in your projects, never fear, it will be very familiar and only takes a few steps to setup.

Tip

We recommend TypeScript in 5 minutes as a good place to start if you are totally new to TypeScript.

Getting Started

Initialize the JS Client

The JS HTTP Client does not maintain any state for your app, it simply provides easy to use APIs so your app can interact with your user's Textile account. You import the library in any library simply.

// No initialization needed, only import
import textile from "@textile/js-http-client"

Below are some basic examples to get you started. If you are interested in a more thorough walk-through, check out the Tour of Textile's examples using the JS HTTP Client.

Get the account display name

const name = await textile.profile.name()

Subscribe to file updates

// The js-http-client returns a `ReadableStream` to be accessed by the caller
// See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream for details
const stream = await textile.subscribe.stream("files")
const reader = stream.getReader()
const read = (result) => { // ReadableStreamReadResult<FeedItem>
  if (result.done) {
    return
  }
  try {
    console.log(result.value)
  } catch (err) {
    reader.cancel(undefined)
    return
  }
  read(await reader.read())
}
read(await reader.read())

Fetch chronological thread updates

await textile.feed.list("<thread-id>")

Create a thread

const thread = await textile.threads.add("Basic")

Add a file

await textile.files.add({ latitude: 48.858093, longitude: 2.294694 }, "", "<thread-id>")

Files stored as blobs

For threads you create that use the /blob schema, you need to add your files slightly differently if your code is running in Node.js or running in the browser.

const data = new Blob(["mmm, bytes..."])
await textile.files.add(
  data,
  "",
  "<thread-id>"
)
const block = await textile.files.add("mmm, bytes...", "", "<thread-id>")

Get a file

In this example, we get a file stored with a /json based schema.

// fileHash is a string hash, commonly found in block.files[index].file.hash
const jsonData = textile.file.content(fileHash)

Files stored as blobs

The same as when writing blob data to threads, you need to be aware of differences when reading blob data if you are in the browser versus if you are in Node.js.

// fileHash is a string hash, commonly found in block.files[index].file.hash
const content = textile.file.content(fileHash)
const reader = new FileReader();
reader.onload = function() {
    console.log(reader.result);
}
reader.readAsText(content);
// fileHash is a string hash, commonly found in block.files[index].file.hash
const content = textile.file.content(fileHash)

Use with redux-saga

Many clients are using libraries such as redux-sagas to manage app state combined with Textile. If you use the above examples, you might hit an issue where you need to declare the context of a function your are calling (detailed in this ticket). Here are a couple examples using Textile to get you started.

Create a thread

export function * createThread(name, key) {
  const thread = yield call([textile.threads, "add"], name, key)
  return thread
}

Get file content

export function * getFile(hash) {
  const file = yield call([textile.file, "content"], hash)
  return file
}

Live playground

You can start playing with some of the core functionality in our developer playground. The playground provides a number of examples that you can run directly against a local Textile node (deamon or desktop installation).

API Documentation

The full API documentation for Textile's JavaScript HTTP Client (js-http-client) can be found at https://textileio.github.io/js-http-client.

Feel free to join the Textile Developer Slack and let us know what you are building. People are always excited to share and learn about new ideas.