SDK

Connect a browser app

Declare your app, let the user sign in and pick a collection, then use the connection’s client.

The SDK is not on npm yet.

Signing in to real collections needs a packaged SDK release, and none is published yet. Until then, write and test your app against createApplicationFixture(). This page will say when a release is out.

1. Write a manifest

The manifest says who your app is and what it needs. Ask only for the capabilities you use; see Authorization.

mdbase-app.json

{
  "manifest_version": 1,
  "id": "dev.example.worklog",
  "name": "Worklog",
  "homepage": "https://worklog.example",
  "redirect_uris": ["https://worklog.example/auth/mdbase/callback"],
  "requirements": {
    "access": "full_collection",
    "contracts": [],
    "capabilities": {
      "contract_version": 2,
      "required": ["collection.read", "records.create", "records.edit"]
    }
  }
}

2. Install

Terminal

npm install @mdbase-dev/sdk

The package is not on npm yet; see the quickstart.

3. Declare the app

mdbase.ts

import { createMdbase } from "@mdbase-dev/sdk";
import manifest from "./mdbase-app.json";

export const mdbase = createMdbase({
  id: "dev.example.worklog",
  name: "Worklog", // must match the manifest's name
  origin: "https://worklog.example",
  environment: "production",
  manifest,
});

Create one createMdbase() entry for your app. origin must be the exact origin your app is served from. The SDK registers your manifest with mdbase when the app starts, so you don’t need an ID from mdbase first. MdbaseConnect is the same entry under its previous name.

4. Sign in and pick a collection

main.ts

import { mdbase } from "./mdbase";

mdbase.subscribe(() => render(mdbase.getSnapshot()));
await mdbase.start();

// Call signIn() straight from the click, so the browser allows its window.
signInButton.onclick = () => mdbase.signIn();

function render(snapshot) {
  const { phase } = snapshot;
  // "signed_out", "authorizing", "choosing", "needs_setup", "ready", …
  showScreen(phase.kind);
  if (phase.kind === "choosing") {
    showPicker(snapshot.collections, (id) => mdbase.select(id));
  }
  if (phase.kind === "ready") startApp(phase.connection.records);
}

Render from the snapshot’s phase. It tells you where the user is: signed out, signing in, choosing a collection, or ready. Switch on phase.kind rather than building your own ready check. When a collection needs set-up first, the phase is needs_setup; assess() says why and configure() applies what your manifest declares.

forget(id) removes a collection from your app’s list on this device. It does not revoke access or delete anything.

5. Use the collection

connection.records is an ordinary MdbaseClient. Everything in Records and operations applies.

worklog.ts

async function startApp(db) {
  const entries = db.live({
    types: ["worklog_entry"],
    order_by: [{ field: "date", direction: "desc" }],
    limit: 50,
  });
  entries.subscribe((state) => renderEntries(state.records));

  addButton.onclick = () =>
    db.create({
      type: "worklog_entry",
      frontmatter: { date: today(), summary: summaryInput.value },
    });
}

Origins

origin is normally your manifest’s HTTPS homepage origin. A Capacitor shell ( capacitor://) or Chrome extension ( chrome-extension://) origin must also be listed under the manifest’s installation_origins. Firefox extension origins are not accepted. Browser redirect_uris must be HTTPS on the homepage origin; a native app can use a private-use scheme based on its manifest ID.