Package Overview

ObjectStack is organized into 72 package manifests across multiple categories. This guide provides an overview of the framework packages, services, drivers, plugins, and adapters in the framework repository.

Package categories at a glance

Core Packages

@objectstack/spec

The Constitution — Protocol schemas, types, and constants for the entire ObjectStack ecosystem.

• Purpose: Zod-first schema definitions for all 15 protocol domains
• Exports: Builder functions (defineStack, defineView, defineApp, defineFlow, defineAgent, defineTool, defineSkill) from the root entry, plus ObjectSchema.create() for objects from the @objectstack/spec/data subpath. Protocol namespaces (Data, UI, System, Automation, AI, API, Identity, Security, Kernel, Cloud, QA, Contracts, Integration, Studio, Shared) are not re-exported from the top-level entry for tree-shaking reasons — import them from subpaths such as @objectstack/spec/data and @objectstack/spec/ui.
• When to use: Import types, schemas, and builder functions when authoring metadata.
• Documentation: Protocol Reference

import { defineStack, defineView } from '@objectstack/spec';
import * as Data from '@objectstack/spec/data';
import * as UI from '@objectstack/spec/ui';
import { ObjectSchema, Field } from '@objectstack/spec/data';

@objectstack/core

The Microkernel — DI container, plugin manager, and service registry.

• Purpose: ObjectKernel with dependency injection, lifecycle hooks, and event bus
• Exports: ObjectKernel, LiteKernel, Plugin interface, service management
• When to use: Bootstrap your application, manage plugins and services
• README: View README

import { ObjectKernel } from '@objectstack/core';
const kernel = new ObjectKernel();

@objectstack/runtime

Runtime Bootstrap — DriverPlugin, AppPlugin, and capability contracts.

• Purpose: High-level runtime bootstrap and plugin composition
• Exports: Runtime configuration, plugin loaders, capability system
• When to use: Use with defineStack() for application setup
• README: View README

@objectstack/objectql

Data Query Engine — MongoDB-style queries with SQL execution.

• Purpose: ObjectQL query engine with filters, aggregations, and window functions
• Exports: Query parser, filter engine, schema registry
• When to use: Advanced query operations, custom data access patterns
• README: View README

@objectstack/metadata

Metadata Management — Loaders, serializers, and overlay system.

• Purpose: Load, validate, and manage metadata from files or runtime
• Exports: Metadata loaders, serializers, overlay system, validation
• When to use: Dynamic metadata loading, multi-source metadata composition
• README: View README

@objectstack/rest

REST API Layer — Auto-generated REST endpoints from metadata.

• Purpose: Automatic REST API generation based on object definitions
• Exports: REST server, route generators, middleware
• When to use: Expose ObjectStack data via REST API
• README: View README

@objectstack/formula

Formula Engine — CEL-based formula compiler/runtime shared by validation, predicates, conditions, and dynamic seed values.

• Purpose: One expression language across hooks, predicates, formula fields, and seed templates
• When to use: Anywhere you write a CEL expression in metadata
• Learn more: Formula skill

@objectstack/platform-objects

Platform Objects Library — The canonical set of sys_* objects shipped with every ObjectStack runtime (users, sessions, organizations, teams, jobs, notifications, email, settings, secrets, …).

• Purpose: Standard system tables and their metadata, so apps don't redefine identity, jobs, or settings
• Not here: per ADR-0029 each domain plugin owns its own objects — sys_audit_log / sys_activity / sys_comment in plugin-audit, sys_record_share in plugin-sharing, sys_approval_request / sys_approval_action in plugin-approvals, the RBAC objects in plugin-security, sys_presence in service-realtime, and sys_metadata* in @objectstack/metadata-core
• When to use: Always — bundled into the runtime

Client Packages

@objectstack/client

Framework-Agnostic SDK — Universal TypeScript client for ObjectStack.

• Purpose: Type-safe client for ObjectStack REST API with batching and error handling
• Exports: ObjectStackClient, query builders, error classes
• When to use: Any JavaScript/TypeScript application (Node, React, Vue, Angular, etc.)
• README: View README

import { ObjectStackClient } from '@objectstack/client';
const client = new ObjectStackClient({ baseUrl: 'https://api.example.com' });

@objectstack/client-react

React Hooks & Bindings — React hooks for ObjectStack.

• Purpose: React hooks for queries, mutations, real-time subscriptions
• Exports: useQuery, useMutation, useRealtimeConnection, useView, useObject, useMetadata, etc.
• When to use: React applications
• README: View README

import { useQuery, useMutation } from '@objectstack/client-react';

Data Drivers

@objectstack/driver-memory

In-Memory Driver — Ephemeral storage for development and testing.

• Purpose: Fast in-memory data storage with full ObjectQL support
• When to use: Development, testing, demos (data is lost on restart)
• README: View README

import { InMemoryDriver } from '@objectstack/driver-memory';

@objectstack/driver-sql

SQL Driver — PostgreSQL, MySQL, SQLite support via Knex.js.

• Purpose: Production-ready SQL database support with migrations
• Supports: PostgreSQL, MySQL, SQLite, and all Knex-compatible databases
• When to use: Traditional relational database deployments
• README: View README

import { SqlDriver } from '@objectstack/driver-sql';
const driver = new SqlDriver({
  client: 'pg',
  connection: { /* PostgreSQL config */ },
});

@objectstack/driver-sqlite-wasm

WASM SQLite Driver — Edge/browser-friendly SQLite via sql.js (WebAssembly).

• Purpose: SQLite running entirely in WebAssembly (no native bindings), with optional fs-backed persistence
• Modes: In-memory (:memory:) or a file path persisted via the persist option
• When to use: Environments without native SQLite, edge/browser runtimes, lightweight local-first storage
• README: View README

import { SqliteWasmDriver } from '@objectstack/driver-sqlite-wasm';
const driver = new SqliteWasmDriver({ filename: ':memory:' });

@objectstack/driver-mongodb

MongoDB Driver — Document-oriented storage backend.

• Purpose: Native MongoDB driver for ObjectQL with document-flavored objects
• When to use: Existing MongoDB infrastructure, document-shaped data — single-tenant deployments only
• Not supported: row-level tenant isolation. The driver refuses to boot when the tenancy posture is not single — see Drivers → Multi-tenancy
• README: View README

@objectstack/driver-turso

Turso / libSQL Driver — Edge-first SQLite with embedded replicas and a remote transport.

• Purpose: Turso/libSQL storage; extends SqlDriver, so all CRUD, schema, filtering and aggregation logic is inherited rather than duplicated
• Modes: local (file / :memory: via better-sqlite3), replica (local file synced from a remote database), remote (pure @libsql/client over HTTP/WebSocket — no native bindings, so it runs on serverless/edge)
• When to use: Globally distributed reads, edge deployments, or a serverless runtime where native SQLite is unavailable
• README: View README

import { TursoDriver } from '@objectstack/driver-turso';
const driver = new TursoDriver({ url: 'libsql://my-db.turso.io', authToken: process.env.TURSO_AUTH_TOKEN });

Platform Services

All services implement contracts from @objectstack/spec/contracts and are kernel-managed singletons.

@objectstack/service-analytics

Analytics Service — Multi-driver analytics with built-in NativeSQL and ObjectQL strategies (the lowest-priority InMemoryStrategy is not built in — it ships in @objectstack/driver-memory).

• Features: Aggregations (measures/dimensions), time dimensions with granularity, dashboard/report widget queries
• When to use: Business intelligence, reporting, metrics dashboards
• README: View README

@objectstack/service-automation

Automation Service — DAG flow execution engine for workflows.

• Features: Autolaunched, screen, and scheduled flows with visual builder support
• When to use: Business process automation, approval workflows, scheduled tasks
• README: View README

@objectstack/service-cache

Cache Service — In-memory caching behind the ICacheService contract.

• Adapters: Memory (the only working adapter). RedisCacheAdapter is a skeleton — every method throws not yet implemented, and CacheServicePlugin({ adapter: 'redis' }) refuses to start. For a real distributed cache, register your own ICacheService via ctx.registerService('cache', impl).
• Features: get / set / delete / has / clear / stats, per-entry TTL, maxSize eviction, lookup & write metrics
• When to use: Performance optimization, reduce database load
• README: View README

@objectstack/service-messaging

Messaging Service — Outbound notification dispatch (ADR-0012).

• Features: MessagingChannel registry, emit() fan-out, always-on inbox channel; email/webhook/push/IM channels plug in
• When to use: Notifying users across channels from flows, hooks, and plugins

@objectstack/service-sms

SMS Service — Outbound SMS delivery (sms service).

• Features: Provider adapters (Aliyun SMS, Twilio), sms settings namespace with live rebind, backs phone-number OTP sign-in/reset and the messaging sms channel
• When to use: Phone OTP first-login / self-service reset, SMS notifications

@objectstack/service-i18n

I18n Service — Internationalization with file-based locales.

• Features: Multi-language support, interpolation, pluralization, fallback chains
• When to use: Multi-language applications, global deployments
• README: View README

@objectstack/service-job

Job Service — Cron and interval-based job scheduling.

• Features: Cron expressions, intervals, one-time jobs, retry logic, history
• When to use: Background tasks, scheduled reports, cleanup jobs
• README: View README

@objectstack/service-queue

Queue Service — Job queues with an in-memory adapter and a durable, database-backed adapter (sys_job_queue). No BullMQ/Redis adapter is shipped.

• Features: Priority, delayed / scheduled delivery, maxAttempts + fixed/exponential backoff, dead-letter queue and replay, idempotency keys; multi-node claim via a lease on the db adapter
• When to use: Async processing, email sending, report generation, webhooks
• README: View README

@objectstack/service-realtime

Realtime Service — in-process pub/sub implementing IRealtimeService, backed by an in-memory adapter.

• Features: publish / subscribe / unsubscribe, channel routing, per-subscription filtering by object name and event type, a maxSubscriptions cap; registers the sys_presence object
• Not included: there is no WebSocket/SSE endpoint and no client transport — IRealtimeService.handleUpgrade is deliberately unimplemented platform-wide until the identity-admission seam exists. The adapter is process-local (single-instance only).
• When to use: Trusted, server-internal subscribers (webhook auto-enqueuer, knowledge sync)
• README: View README

@objectstack/service-storage

Storage Service — File storage with local filesystem and S3 adapters.

• Features: Upload, download, signed URLs, multipart uploads, metadata
• When to use: File attachments, document management, media storage
• README: View README

@objectstack/service-package

Package Registry Service — Publish, version, and retrieve ObjectStack metadata packages from the sys_packages table.

• Features: Upsert by (id, version), SHA-256 integrity hash, latest resolution, bulk list/delete
• When to use: Marketplace backends, internal tenant-facing registries, CI-driven metadata distribution
• README: View README

@objectstack/service-settings

Settings Service — Hierarchical, validated application settings backed by metadata.

• Features: Per-org / per-user settings, Zod-validated namespaces, default fallbacks
• When to use: Application/feature configuration that must be editable at runtime
• README: View README

Official Plugins

@objectstack/plugin-auth

Authentication Plugin — Better-auth integration with ObjectQL.

• Features: Email/password, OAuth providers, session management, bearer-token auth, password reset and email verification (authorization itself lives in plugin-security)
• When to use: User authentication and identity
• README: View README

@objectstack/plugin-security

Security Plugin — RBAC, permissions, field-level security.

• Features: Role-based access control, object/field permissions, row-level security, owner_id auto-stamp
• When to use: Multi-user applications with access control requirements
• README: View README

@objectstack/organizations (enterprise)

Organization Scoping — Multi-org (a.k.a. "soft" multi-tenant) row-level scoping. Ships as a separate, closed-source enterprise package — it is not part of the open framework repo. It composes with the Layer 0 tenant wall in plugin-security (tenant-layer.ts).

• Features: organization_id auto-stamp on insert; every query is AND-composed against the tenant wall, so no row outside the caller's organization scope is ever returned
• When to use: Multi-organization SaaS where every row is scoped to an organization. Enable by setting OS_TENANCY_POSTURE to a walled posture — group (union read across every organization the caller belongs to) or isolated (the hard per-organization wall) — and installing @objectstack/organizations; if a walled posture is requested but the package is missing, the platform refuses to boot (override with OS_ALLOW_DEGRADED_TENANCY=1). The legacy OS_MULTI_ORG_ENABLED boolean is still honoured, but only as a fallback input when OS_TENANCY_POSTURE is unset, and it can only ever select isolated — never gate application code on it (ADR-0105 D1). See Tenancy Postures & Membership for how the posture resolves

@objectstack/plugin-audit

Audit Plugin — Compliance audit trail and activity logging.

• Features: CRUD audit logs, field-level changes, security events, compliance reports
• When to use: SOC 2, HIPAA, GDPR compliance, security monitoring
• README: View README

@objectstack/mcp

MCP Server Plugin — Expose ObjectStack via Model Context Protocol.

• Features: AI tools, data resources, prompt templates for Claude, Cursor, Cline
• When to use: AI agent integration, MCP-compatible tools
• README: View README

@objectstack/plugin-hono-server

Hono Server Plugin — HTTP server with Hono framework.

• Features: Lightweight HTTP server, middleware support, edge-compatible
• When to use: Serve ObjectStack REST API with Hono
• README: View README

@objectstack/plugin-dev

Development Assembly Plugin — one plugin that wires the real platform stack for zero-config local development.

• Features: Auto-assembles ObjectQL + in-memory driver + auth + security + Hono server + REST + dispatcher + app metadata, plus optional real services when installed (storage, realtime, i18n); registers no stubs — a slot no plugin fills stays empty, as in production (ADR-0115); refuses to boot with NODE_ENV=production (OS_ALLOW_DEV_PLUGIN escape hatch, which brands the override in the boot log and on the ready banner instead of overriding silently)
• When to use: Zero-config local development and playgrounds
• README: View README

@objectstack/plugin-approvals

Approvals Plugin — Contributes the approval flow node (ADR-0019): an approval runs on the one automation engine as a durable-pause node, backed by sys_approval_request / sys_approval_action.

• Features: Approver resolution (manager/position/department/team/field/expression/org_membership_level/user), first_response / unanimous / quorum / per_group, record lock, status mirror, per-node SLA escalation, audit trail
• When to use: Any flow that needs human sign-off (expense, quote, contract, …) — add an approval node and branch on approve / reject

@objectstack/plugin-sharing

Sharing Plugin — Record-level sharing engine for collaborative access.

• Features: Manual shares, sharing rules, team-based access, sys_record_share
• When to use: Teams that need to grant per-record access beyond RBAC

@objectstack/plugin-email

Email Plugin — Outbound email channel and templates.

• Features: Provider transports (Postmark, Resend), a minimal mustache-style {{placeholder}} template renderer, delivery tracking on sys_email
• When to use: Transactional and workflow-driven email

@objectstack/plugin-webhooks

Webhooks Plugin — Outbound HTTP webhook delivery.

• Features: Subscriptions, retries, signed payloads, delivery logs
• When to use: Integrating ObjectStack events with external systems

@objectstack/plugin-reports

Reports Plugin — Metadata-driven report rendering and scheduling.

• Features: Tabular/aggregate reports, scheduled delivery, exports
• When to use: Operational reporting on top of business objects

Framework Adapters

The open edition ships the Hono adapter. Hono runs on Node.js, Bun, Deno, and edge runtimes (Cloudflare Workers, Vercel Edge), covering most deployments. For another framework, build a thin adapter on the public HttpDispatcher API (the previous Express/Fastify/Next/Nest/Nuxt/SvelteKit adapters were ~50-line wrappers and can be vendored out-of-tree).

@objectstack/hono

Hono Adapter — the supported HTTP adapter; edge-native and multi-runtime.

• Use case: Node.js, Bun, Deno, Cloudflare Workers, Vercel Edge
• README: View README

Developer Tools

@objectstack/cli

CLI Tool — Command-line interface for ObjectStack.

• Commands: serve, dev, start, doctor, compile, build, validate, generate, package, meta, … (binary is os / objectstack)
• When to use: Development, deployment, project management
• README: View README

npx os serve --dev

create-objectstack

Project Scaffolding — Create new ObjectStack projects.

• Templates: blank (default, bundled), plus remote templates todo, compliance, content, contracts, procurement
• When to use: Start a new ObjectStack project
• README: View README

npx create-objectstack my-app

Utility Packages

@objectstack/types

Shared Type Utilities — Dependency-light runtime contracts that break circular imports between packages.

• Exports: IKernel, RuntimePlugin, RuntimeContext, plus env-reading (readEnvWithDeprecation), degraded-boot, error-leak, and module-not-found helpers
• When to use: Imported automatically by other packages
• README: View README

Package Selection Guide

ObjectStack composes packages at two layers:

1. Metadata is declared inside defineStack({...}) (objects, views, flows, agents, …) and lives in objectstack.config.ts.
2. Runtime plugins/services/drivers are wired into the host kernel through kernel.use(...), @objectstack/runtime, or a custom adapter host.

The snippets below illustrate which runtime packages you typically reach for in each scenario. See the Quick Start and CLI guide for the full bootstrap pattern.

For New Projects (edge / AI-native)

// Host bootstrap (exact shape depends on adapter)
import { ObjectKernel, DriverPlugin } from '@objectstack/runtime';
import { ObjectQLPlugin } from '@objectstack/objectql';
import { SqliteWasmDriver } from '@objectstack/driver-sqlite-wasm';
// Open edition: AI is exposed via @objectstack/mcp (BYO-AI), not an in-process plugin.

const kernel = new ObjectKernel();
await kernel.use(new ObjectQLPlugin());
// A driver is not a plugin — wrap it in `DriverPlugin` before `kernel.use()`.
await kernel.use(new DriverPlugin(new SqliteWasmDriver({ filename: ':memory:' })));
// Point your own AI (Claude/Cursor/local model) at objects, queries & actions over MCP.
await kernel.bootstrap();

For Traditional Web Apps

import { DriverPlugin } from '@objectstack/runtime';
import { SqlDriver } from '@objectstack/driver-sql';
import { AuthPlugin } from '@objectstack/plugin-auth';
import { QueueServicePlugin } from '@objectstack/service-queue';

await kernel.use(new DriverPlugin(new SqlDriver({ client: 'pg', connection: { /* … */ } })));
await kernel.use(new AuthPlugin({ /* … */ }));
await kernel.use(new QueueServicePlugin({ adapter: 'auto' }));

For Enterprise Applications

import { SecurityPlugin } from '@objectstack/plugin-security';
import { AuditPlugin } from '@objectstack/plugin-audit';
import { AnalyticsServicePlugin } from '@objectstack/service-analytics';

await kernel.use(new SecurityPlugin({ /* … */ }));
await kernel.use(new AuditPlugin());
await kernel.use(new AnalyticsServicePlugin({ /* … */ }));

The official plugin and service packages above export plugin classes you instantiate (new XPlugin(options)) — check each package's README.md for its option shape. Some infrastructure packages ship a create*Plugin factory instead (createRestApiPlugin, createDispatcherPlugin, createPlatformObjectsPlugin, …). Either way the result implements the Plugin interface kernel.use() accepts.

Next Steps

• Architecture Overview: Learn the architecture
• Quick Start: Build your first app
• API Reference: Explore the API
• Examples: Browse examples