Getting Started

Holster has two roles: relay servers that store data and pass updates between devices, and clients that connect to them. Both roles use the same code base, which means they share the same improvements.

Install

npm install @mblaney/holster

The same package is used everywhere, by relays and clients alike. Which file you import depends on how your application runs:

File

Use it when

src/holster.js

Running in Node.js, Deno or Bun, or in the browser with a build step that bundles your JavaScript.

build/holster.js

Loading Holster directly in the browser, with no build step. It's a minified copy of the same code.

dist/holster.js

Using the TypeScript version. Its type definitions are in dist/src.

Run a relay

Create a relay.js file:

import Holster from "@mblaney/holster/src/holster.js"

Holster({port: 8765})

Then start it with node relay.js. That's all you need to run a relay on port 8765. Passing a port (or an existing server or wss) is what makes Holster act as a server rather than a client.

The defaults for memory and storage are conservative, to suit the browser. On a relay you'll usually want larger values to match your server's resources, see Options.

In production

You can keep a relay running with pm2:

npm install pm2 -g
export NODE_ENV=production
pm2 startup # then follow its instructions
pm2 start relay.js
pm2 save

To accept connections through a web server and use secure WebSockets (wss://), see the Apache example.

Connect a client

In the browser, pass the relay's address to Holster():

<script type="module">
  import Holster from "./node_modules/@mblaney/holster/build/holster.js"

  const holster = Holster("wss://your-relay-host")
  globalThis.holster = holster
</script>

This loads the minified build directly, with no build step needed. If your application has a build step that bundles its JavaScript, such as Vite or webpack, import @mblaney/holster/src/holster.js instead, and it's minified along with the rest of your code.

Holster doesn't rewrite the address, so it needs to start with ws:// or wss://. If no address is given, Holster connects to ws://localhost:8765. See Options for connecting to more than one relay, and for storing data locally with IndexedDB.

Read and write data

Every request starts with get(), and data is returned either to a callback or with await:

// Write some data.
await holster.get("profile").put({name: "Alice", city: "Brisbane"})

// Read it back.
const profile = await holster.get("profile")
console.log(profile) // {name: "Alice", city: "Brisbane"}

// Read one nested value.
const city = await holster.get("profile").next("city")

// Listen for changes made on any device.
holster.get("profile").on(data => console.log("updated:", data))

The Holster API overview explains how requests are chained, and the difference between callbacks and await. To try these lines yourself, see Running the examples, which sets up Node's interactive shell.

Repo examples

The Holster repository includes a server and example pages:

git clone https://github.com/mblaney/holster.git
cd holster
npm install
node src/index.js

Then open http://localhost:3000/examples/index.html. The examples log their results to the console, where the holster object is also available to try the API yourself. There are examples for the User API (user.html) and the Wire API (wire.html) too.

The repository also has a Dockerfile, if you'd rather run it with Docker:

docker build -t holster .
docker run -p 3000:3000 -p 8765:8765 holster