Kroxt BaaS SDK

Official JavaScript and TypeScript SDK for Kroxt BaaS.

Installation

npm install @kroxt/baas-sdk

Quick Start

Create a client with your project ID and API key:

import Kroxt from "@kroxt/baas-sdk";

const kroxt = new Kroxt({
  projectId: "PROJECT_ID",
  apiKey: "PROJECT_API_KEY",
});

const posts = await kroxt.collection("posts").limit(10).get();

Authentication

Sign a user in:

await kroxt.auth.login({
  email: "[email protected]",
  password: "password",
});

Read the active user session:

const user = await kroxt.auth.me();

Sign out:

await kroxt.auth.logout();

Register a project user:

await kroxt.auth.register({
  email: "[email protected]",
  password: "password",
  displayName: "Ada",
});

Collections

Create a document:

type Post = {
  title: string;
  published: boolean;
  views: number;
};

const posts = kroxt.collection<Post>("posts");

const created = await posts.create({
  title: "Hello Kroxt",
  published: true,
  views: 1,
});

Query documents:

const posts = kroxt.collection<Post>("posts");

const publishedPosts = await posts
  .where("published", true)
  .where("views", "greaterThan", 10)
  .orderBy("createdAt", "desc")
  .limit(20)
  .get();

Update or delete a document:

await posts.update(created._id, { views: 2 });
await posts.delete(created._id);

Pagination

const page = await kroxt.collection("posts").paginate({
  page: 1,
  limit: 20,
});

console.log(page.items, page.total, page.hasNext);

Realtime

Subscribe to collection changes:

const channel = kroxt.realtime.collection("posts");

channel
  .subscribe()
  .on("created", (post) => {
    console.log("New post:", post);
  });

Use custom realtime channels:

kroxt.realtime
  .channel("room:lobby")
  .subscribe()
  .on("message", (payload) => {
    console.log(payload);
  });

Storage and Functions

Upload a file:

const uploaded = await kroxt.storage.upload(file);

Invoke a serverless function:

const result = await kroxt.functions.invoke("send-welcome-email", {
  userId: "USER_ID",
});

Configuration

const kroxt = new Kroxt({
  projectId: "PROJECT_ID",
  apiKey: "PROJECT_API_KEY",
  timeout: 30000,
  retries: 3,
  autoRefresh: true,
  debug: false,
});

Bring Your Own MongoDB

By default, your project data is stored in the Kroxt BaaS managed database. To host all of your project's data in your own MongoDB database instead, pass a mongodbUri:

import { Kroxt } from "@kroxt/baas-sdk";

export const baas = new Kroxt({
  projectId: "PROJECT_ID",
  apiKey: "PROJECT_API_KEY",
  // Optional: host your project data in your own MongoDB database.
  mongodbUri: "mongodb://user:pass@host:27017/yourdb",
});

When mongodbUri is provided, the SDK registers it with the backend (which connects to your database server-side) and the project switches to external hosting. All collections, documents, users, and storage metadata for the project are then stored in your MongoDB instance, namespaced under kroxt_project_<projectId> so multiple projects can safely share one database.

If you omit mongodbUri (or pass mongodb_uri), the project continues to use the Kroxt BaaS managed database.

You can also manage the connection explicitly:

// (Re)configure the external database
await baas.connectDatabase("mongodb://user:pass@host:27017/yourdb");

// Inspect the current hosting configuration
const config = await baas.getDatabaseConfig();

// Revert to the Kroxt BaaS managed database
await baas.disconnectDatabase();

Note: the connection string is sent over HTTPS and encrypted at rest on the server. Never log it. The backend validates connectivity before enabling external hosting.

Package Formats

This package ships CommonJS, ESM, and TypeScript declarations.

import Kroxt from "@kroxt/baas-sdk";

const { Kroxt } = require("@kroxt/baas-sdk");

License

MIT