Connect SDK

Try the SDK locally

Run a typed read, create, update, and query against an in-memory mdbase collection with no account or service.

No account, connector, or hosted service is required.

This example uses the real typed collection client and the deterministic developer sandbox. It keeps every record in memory and makes no network requests.

Prerequisites

Git;
Node 24 LTS;
Corepack, which installs the repository's pinned pnpm version.

1. Build the current packages

The Connect packages await their first npm publication. Build the exact beta packages from the public repository for this example.

Terminal

git clone https://github.com/mdbase-dev/mdbase-connect.git
cd mdbase-connect
corepack enable
pnpm install
pnpm build

2. Download and run the complete example

Save the example inside the developer package so Node resolves the local workspace packages. The final command prints the result and exits.

Terminal

curl -fsSLo packages/devkit/sandbox-quickstart.mjs \
  https://mdbase.dev/examples/sandbox-quickstart.mjs

node packages/devkit/sandbox-quickstart.mjs

You can also download the example file and save it as packages/devkit/sandbox-quickstart.mjs.

3. See what the example does

packages/devkit/sandbox-quickstart.mjs

import { unwrapOperation } from "@mdbase/connect";
import { createSandbox } from "@mdbase/connect-dev";

const { client, transport } = createSandbox({
  records: [{
    path: "tasks/first.md",
    types: ["task"],
    frontmatter: {
      type: "task",
      title: "Read the collection",
      completed: false
    }
  }]
});

const first = unwrapOperation(
  await client.read({ path: "tasks/first.md" })
);

const created = unwrapOperation(await client.create({
  type: "task",
  path: "tasks/second.md",
  frontmatter: {
    type: "task",
    title: "Update one record",
    completed: false
  }
}));

const updated = unwrapOperation(await client.update({
  path: created.path,
  patch: { completed: true },
  if_revision: created.revision
}));

const tasks = unwrapOperation(await client.query({
  types: ["task"],
  limit: 20
}));

console.log(`Read: ${first.frontmatter.title}`);
console.log(
  `Updated: ${updated.path} (completed: ${updated.frontmatter.completed})`
);
console.log(`Task records: ${tasks.results.length}`);
console.log(
  `Markdown paths: ${transport.snapshot()
    .map((record) => record.path)
    .join(", ")}`
);

createSandbox() returns the same MdbaseCollectionClient boundary used by a connected collection. The example reads one seed record, creates a second record, updates it with its revision token, and queries both task records.

4. Check the expected result

Expected output

Read: Read the collection
Updated: tasks/second.md (completed: true)
Task records: 2
Markdown paths: tasks/first.md, tasks/second.md

A stale revision fails with a concurrent_modification diagnostic. The sandbox also supports typed CRUD, pagination, read defaults, and change cursors. CEL expressions, authorization, routing, and filesystem behavior belong in real-stack integration tests.

5. Continue to a real collection

The next guide adds an application manifest, a provisionable workout contract, browser authorization, and one approved local or hosted collection.

Connect a browser application Understand the test boundary