orbiter-client

A framework-agnostic Node.js client for Orbiter. Use it in SvelteKit, Next.js, Nuxt, Remix, or any other Node.js framework — no Vite virtual modules required.

Install

npm install @a83/orbiter-client

Quick start

import { createClient } from '@a83/orbiter-client';

const orb = createClient('./content.pod');

const posts = await orb.getCollection('posts');
const post  = await orb.getEntry('posts', 'my-post');

Call createClient() once at the module level (server singleton). The returned client keeps the SQLite connection open — opening once and reusing is faster than opening per request.

SvelteKit

// src/lib/orbiter.js — create once, import everywhere
import { createClient } from '@a83/orbiter-client';
export const orb = createClient('./content.pod');

// src/routes/blog/+page.server.js
import { orb } from '$lib/orbiter';

export async function load() {
  const posts = await orb.getCollection('posts');
  return { posts };
}

// src/routes/blog/[slug]/+page.server.js
import { orb } from '$lib/orbiter';

export async function load({ params }) {
  const post = await orb.getEntry('posts', params.slug);
  if (!post) error(404);
  return { post };
}

Next.js (App Router)

// lib/orbiter.js
import { createClient } from '@a83/orbiter-client';
export const orb = createClient('./content.pod');

// app/blog/page.jsx  (Server Component)
import { orb } from '@/lib/orbiter';

export default async function BlogPage() {
  const posts = await orb.getCollection('posts');
  return (
    <ul>
      {posts.map(p => <li key={p.slug}>{p.data.title}</li>)}
    </ul>
  );
}

// app/blog/[slug]/page.jsx
import { orb } from '@/lib/orbiter';
import { notFound } from 'next/navigation';

export async function generateStaticParams() {
  const posts = await orb.getCollection('posts');
  return posts.map(p => ({ slug: p.slug }));
}

export default async function PostPage({ params }) {
  const post = await orb.getEntry('posts', params.slug);
  if (!post) notFound();
  return <article dangerouslySetInnerHTML={{ __html: post.data.body }} />;
}

In Next.js, the POD must be on the same machine as the Node.js server. For static export (next export), use createClient inside generateStaticParams and page components — Next.js runs these at build time.

API

createClient(podPath)

Opens the POD and returns a client. podPath is resolved relative to process.cwd().

orb.getCollection(name)

Returns all published entries (default locale) sorted by sort_order, then updated_at.

orb.getEntry(collection, slug)

Returns a single published entry by slug (default locale), or null.

orb.getLocaleCollection(name, locale)

Returns published entries for a specific locale.

const dePosts = await orb.getLocaleCollection('posts', 'de');

orb.getLocaleEntry(collection, slug, locale)

Returns an entry in the requested locale, falling back to the default locale if no translation exists.

const post = await orb.getLocaleEntry('posts', 'my-post', 'de');

orb.getPreviewEntry(collection, slug, previewToken)

Returns any entry (including drafts) if previewToken matches the site's preview token. Returns null on mismatch.

orb.locale / orb.locales

orb.locale   // 'en'              — default locale from Settings
orb.locales  // ['en', 'de', 'fr'] — all configured locales

orb.close()

Closes the SQLite connection. Call on process shutdown if needed — in most long-lived server processes this is optional.

Relation fields

Relation fields are resolved automatically at query time — the UUID reference is replaced with the full entry object, identical to the orbiter:collections behaviour.