Quick Start

Get started with the SnackBase JavaScript SDK in this 5-minute guide. You’ll learn how to initialize the client, authenticate users, and perform CRUD operations on your collections.

Prerequisites

Complete the Installation guide
Have a SnackBase instance running with an existing collection
Have your API URL ready (e.g., https://your-project.snackbase.dev)

Step 1: Initialize the Client

Create a new SnackBase client instance with your configuration:

import { SnackBaseClient } from "@snackbase/sdk";

const client = new SnackBaseClient({
  baseUrl: "https://your-project.snackbase.dev",
  // Optional: Add an API key for server-side operations
  apiKey: process.env.SNACKBASE_API_KEY,
});

For client-side applications, omit the apiKey parameter. Users will authenticate with their own credentials.

Step 2: Authenticate a User

Email and Password

// Log in with email and password
const auth = await client.auth.loginWithPassword({
  account: "your-account-slug",
  email: "[email protected]",
  password: "secure-password",
});

console.log("Logged in as:", auth.user.email);
console.log("Account:", auth.account.name);

Register a New User

// Register a new user and account
const result = await client.auth.register({
  email: "[email protected]",
  password: "secure-password",
  accountName: "My Account",
});

console.log("User registered:", result.user.email);

Step 3: Query Records

List Records

// Get all records from a collection
const posts = await client.records.list("posts");

console.log("Total:", posts.total);
console.log("Items:", posts.items);

// With filtering and sorting
const publishedPosts = await client.records.list("posts", {
  filter: { status: "published" },
  sort: "-createdAt",
  limit: 10,
});

Get a Single Record

// Get a specific record by ID
const post = await client.records.get("posts", "record-id");

console.log(post.title);
console.log(post.content);

Using the Query Builder

For complex queries, use the fluent query builder:

const results = await client.records
  .query("posts")
  .select("id", "title", "author.name")
  .filter("status", "=", "published")
  .filter("createdAt", ">", "2024-01-01")
  .sort("createdAt", "desc")
  .page(1, 20)
  .get();

console.log(results.items);

Step 4: Create Records

// Create a new record
const newPost = await client.records.create("posts", {
  title: "My First Post",
  content: "This is my first post using SnackBase!",
  status: "published",
  views: 0,
});

console.log("Created post with ID:", newPost.id);

Step 5: Update Records

Full Update (PUT)

Replaces all fields of the record:

const updated = await client.records.update("posts", "record-id", {
  title: "Updated Title",
  content: "Updated content",
  status: "published",
  views: 10,
});

Partial Update (PATCH)

Updates only the specified fields:

const patched = await client.records.patch("posts", "record-id", {
  views: 15,
});

Use patch() for partial updates to avoid overwriting fields you don’t intend to change.

Step 6: Delete Records

await client.records.delete("posts", "record-id");
console.log("Post deleted");

Step 7: Real-Time Subscriptions

Subscribe to real-time updates for a collection:

// Connect to the real-time service
await client.realtime.connect();

// Subscribe to collection events
await client.realtime.subscribe("posts", ["create", "update", "delete"]);

// Listen for events
client.realtime.on("posts.create", (data) => {
  console.log("New post created:", data);
});

client.realtime.on("posts.update", (data) => {
  console.log("Post updated:", data);
});

// Unsubscribe when done
const unsubscribe = client.realtime.on("posts.delete", (data) => {
  console.log("Post deleted:", data);
});

// Call unsubscribe() to stop listening
unsubscribe();

Complete Example

Here’s a complete example combining all concepts:

import { SnackBaseClient } from "@snackbase/sdk";

async function main() {
  // Initialize
  const client = new SnackBaseClient({
    baseUrl: "https://your-project.snackbase.dev",
  });

  // Authenticate
  const auth = await client.auth.loginWithPassword({
    account: "my-account",
    email: "[email protected]",
    password: "password",
  });

  console.log("Authenticated as:", auth.user.email);

  // Query with the builder
  const posts = await client.records
    .query("posts")
    .filter("status", "=", "published")
    .sort("createdAt", "desc")
    .page(1, 10)
    .get();

  console.log(`Found ${posts.total} published posts`);

  // Create a new post
  const newPost = await client.records.create("posts", {
    title: "Hello, SnackBase!",
    content: "My first post",
    status: "published",
  });

  console.log("Created:", newPost.id);

  // Update the post
  const updated = await client.records.patch("posts", newPost.id, {
    views: 1,
  });

  console.log("Updated:", updated.views);

  // Cleanup
  await client.records.delete("posts", newPost.id);
  console.log("Deleted");
}

main().catch(console.error);

Next Steps

Query Builder - Learn advanced querying
Realtime - Build real-time features
React Integration - Use with React applications
Error Handling - Handle errors gracefully

Check out the Feature Voting App for a complete example demonstrating authentication, CRUD operations, real-time subscriptions, and React integration with the SDK.

Getting Started

Authentication

Core Services

Admin Services

Automation Services

Query Builder

Realtime

React Integration

Error Handling

Reference

Prerequisites

Step 1: Initialize the Client

Step 2: Authenticate a User

Email and Password

Register a New User

Step 3: Query Records

List Records

Get a Single Record

Using the Query Builder

Step 4: Create Records

Step 5: Update Records

Full Update (PUT)

Partial Update (PATCH)

Step 6: Delete Records

Step 7: Real-Time Subscriptions

Complete Example

Next Steps

​Prerequisites

​Step 1: Initialize the Client

​Step 2: Authenticate a User

​Email and Password

​Register a New User

​Step 3: Query Records

​List Records

​Get a Single Record

​Using the Query Builder

​Step 4: Create Records

​Step 5: Update Records

​Full Update (PUT)

​Partial Update (PATCH)

​Step 6: Delete Records

​Step 7: Real-Time Subscriptions

​Complete Example

​Next Steps

Prerequisites

Step 1: Initialize the Client

Step 2: Authenticate a User

Email and Password

Register a New User

Step 3: Query Records

List Records

Get a Single Record

Using the Query Builder

Step 4: Create Records

Step 5: Update Records

Full Update (PUT)

Partial Update (PATCH)

Step 6: Delete Records

Step 7: Real-Time Subscriptions

Complete Example

Next Steps