use-vibes

Your Vibes app's database,
from any JS backend

Your app's live data is accessible outside the browser — from Node, Deno, Bun, Cloudflare Workers, or any runtime that can run npm packages.

before you start

Prerequisites

npx vibes-diy login$ npx vibes-diy login

Install the package. Works with npm, pnpm, and yarn.

npm install use-vibes$ npm install use-vibes

// Deno / Bun: import { fireproof } from "https://esm.sh/use-vibes"

start here

Minimal working example

Connect to the same database that backs your Vibes app. You need two things from your vibe's URL (vibes.diy/vibe/userSlug/appSlug): the appSlug, and the database name your App.jsx passes to fireproof().

import { fireproof } from "use-vibes"; // appSlug is the last segment of your vibe's URL: vibes.diy/vibe// const db = fireproof("todos", { appSlug: "my-todo-app" }); const ok = await db.put({ text: "hello from Node" }); const doc = await db.get(ok.id); const { docs } = await db.query("type", { key: "todo" }); db.subscribe((changes) => { console.log("live update:", changes); }, true);import { fireproof } from "use-vibes";

// appSlug is the last segment of your vibe's URL: vibes.diy/vibe/<userSlug>/<appSlug>
const db = fireproof("todos", { appSlug: "my-todo-app" });

const ok = await db.put({ text: "hello from Node" });
const doc = await db.get(ok.id);
const { docs } = await db.query("type", { key: "todo" });

db.subscribe((changes) => {
console.log("live update:", changes);
}, true);

fireproof("todos", { appSlug }) — opens the named database within that vibe; pass appSlug explicitly so the script works from any directory
put(doc) — write a document; returns { id, clock }
get(id) — fetch a document by id
query(field, opts) — index query by field value
subscribe(fn, true) — live updates over WebSocket; second arg fires immediately with current state

configuration

How defaults resolve

When you call fireproof("todos") with no options, these defaults apply in order.

Field	Default
apiUrl	`VIBES_DIY_API_URL` env var, then `https://vibes.diy/api`
appSlug	`VIBES_APP_SLUG` env var, then `basename(process.cwd())` — pass explicitly to avoid connecting to the wrong vibe
getToken	device cert from `npx vibes-diy login` keybag
userHandle	looked up automatically from your account on first request (pass it to skip the round-trip)

Explicit config

For CI, Wrangler, or service accounts — environments without a device keybag.

const db = fireproof("todos", { apiUrl: "https://vibes.diy/api", appSlug: "my-app", userHandle: "alice", getToken: async () => myTokenResult, });const db = fireproof("todos", {
  apiUrl: "https://vibes.diy/api",
  appSlug: "my-app",
  userHandle: "alice",
  getToken: async () => myTokenResult,
});

important

Instance caching

These rules apply per process — important for long-running scripts and Workers.

fireproof("todos") === fireproof("todos") — same name returns the same instance within a process
Multiple database names share one WebSocket connection
First call's opts win for the whole process — later calls with different names inherit the connection settings

v1 limitations

What's not supported yet

File uploads (_files field) are not yet supported — pure document workflows only
Inside a Vibes iframe, the import is automatically rewritten to the postMessage bridge — this factory is only for external scripts
In the browser a Vibes app talks to a local-first replica (instant, offline). From an external backend you're a remote client of that same data — the await-to-server calls shown here.

reference

Available methods

These are the only methods. Do not use others.

Method	Notes
put(doc)	Write a document. Returns `{ id, clock }`. verified
get(id)	Fetch a document by id. verified
del(id)	Delete a document by id. verified
query(field, opts)	Index query by field value. verified
subscribe(fn, runNow?)	Live updates over WebSocket. Second arg fires immediately. verified
allDocs(opts?)	Fetch all documents. listed, unverified
bulk(docs)	Batch write. listed, unverified

what people build with it

Integration patterns

Cron-powered workflows, webhook fan-out, export & reporting, seed and migration scripts, health checks, multi-surface sync. Two ways to run them: hosted — every vibe can ship a backend.js with webhook endpoints, change reactions, and scheduled jobs built in, no server of yours required — or in your own stack with this package, when the logic needs to live beside your existing code, secrets, or CI. The production recipes for both are in the patterns cookbook.

Ready to connect?

Open your Vibes app, grab the appSlug from its URL and the database name from your App.jsx, and start reading data from your script.

Open Vibes DIY → ← Creator Documentation

Your Vibes app's database,from any JS backend