Package Overview

ObjectStack is organized into 51 publishable packages across multiple categories. This guide provides a complete overview of each package, its purpose, and when to use it. Counts are kept in sync with the packages/ directory 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: Data, UI, System, Automation, AI, API, Identity, Security, Kernel, Cloud, QA, Contracts, Integration, Studio, Shared namespaces, plus builder functions (defineStack, defineView, defineApp, defineFlow, defineAgent, defineTool, defineSkill) and ObjectSchema.create() for objects.
• When to use: Import types, schemas, and builder functions when authoring metadata.
• Documentation: Protocol Reference

import { Data, UI, defineStack, defineView } from '@objectstack/spec';
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 ObjectOS runtime (users, sessions, approvals, sharing, audit, …).

• Purpose: Standard system tables and their metadata, so apps don't redefine identity, audit, or approvals
• When to use: Always — bundled into the runtime
• README: View README

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, useRealtime, useAuth, 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-turso

Turso/libSQL Driver — Edge-first SQLite with embedded replicas.

• Purpose: Edge-native SQLite with local-first architecture and multi-tenancy
• Modes: Remote (edge), Embedded Replica (local-first), Local (dev)
• When to use: Vercel Edge, Cloudflare Workers, global low-latency deployments
• README: View README

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

@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
• README: View README

Platform Services

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

@objectstack/service-ai

AI Service — LLM adapter layer, conversation management, tool registry.

• Supports: OpenAI, Anthropic, Google, custom providers via Vercel AI SDK
• Features: Multi-model support, streaming, tool calling, conversation history
• When to use: AI-powered features, chatbots, agents, RAG pipelines
• README: View README

@objectstack/service-analytics

Analytics Service — Multi-driver analytics with NativeSQL, ObjectQL, InMemory strategies.

• Features: Aggregations, time series, funnels, dashboards
• 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 and Redis caching.

• Adapters: Memory (dev), Redis (production)
• Features: TTL, namespaces, pattern matching, statistics
• When to use: Performance optimization, reduce database load
• README: View README

@objectstack/service-feed

Feed/Chatter Service — Activity feed with comments, reactions, subscriptions.

• Features: Comments, @mentions, reactions, field change tracking, presence
• When to use: Collaboration features, activity streams, social features
• README: View README

@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 in-memory and BullMQ adapters.

• Features: Priority queues, retry, rate limiting, worker pools, job events
• When to use: Async processing, email sending, report generation, webhooks
• README: View README

@objectstack/service-realtime

Realtime Service — WebSocket pub/sub for live updates.

• Features: Channels, presence, broadcasting, typing indicators, cursor tracking
• When to use: Real-time dashboards, collaborative editing, live notifications
• 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-tenant

Multi-Tenant Service — Tenant context, routing, and isolation for SaaS deployments.

• Features: Tenant resolution from host/header/cookie, per-tenant metadata and data isolation
• When to use: Any multi-tenant SaaS on ObjectStack
• README: View README

@objectstack/service-cloud

Cloud Control-Plane Service — Bridge between ObjectOS runtimes and the hosted control plane (artifact API, project versions).

• Features: Artifact fetch/cache, project version selection, telemetry hooks
• When to use: When deploying through the ObjectStack hosted cloud or a self-hosted control plane
• 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, RBAC
• When to use: User authentication and authorization
• 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/plugin-org-scoping

Organization Scoping Plugin — Multi-org (a.k.a. "soft" multi-tenant) row-level scoping built on top of plugin-security.

• Features: organization_id auto-stamp on insert, per-org seed-data replay, default-org bootstrap, orphan-row claim hook
• When to use: Multi-organization SaaS where every row is scoped to an sys_organization. Enable by setting OS_MULTI_TENANT=true (registered automatically before plugin-security)
• README: View README

@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/plugin-mcp-server

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-msw

MSW Plugin — Mock Service Worker for testing.

• Features: Mock HTTP handlers for testing without real server
• When to use: Frontend testing, integration tests
• README: View README

@objectstack/plugin-dev

Developer Tools Plugin — Development-time utilities.

• Features: Metadata validation, schema introspection, debugging tools
• When to use: Development and debugging
• 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 (user/role/team/department/manager/field/queue), first_response / unanimous, 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
• README: View README

@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
• README: View README

@objectstack/plugin-email

Email Plugin — Outbound email channel and templates.

• Features: Provider adapters, MJML templates, delivery tracking
• When to use: Transactional and workflow-driven email
• README: View README

@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
• README: View README

@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
• README: View README

Framework Adapters

ObjectStack integrates with popular web frameworks via adapters. All adapters expose ObjectStack's REST API through the framework's routing system.

@objectstack/express

Express.js Adapter — Traditional Node.js web framework.

• Use case: Classic Node.js applications, RESTful APIs
• README: View README

@objectstack/fastify

Fastify Adapter — High-performance Node.js framework.

• Use case: Performance-critical applications, microservices
• README: View README

@objectstack/hono

Hono Adapter — Edge-native web framework.

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

@objectstack/nestjs

NestJS Adapter — Enterprise TypeScript framework.

• Use case: Enterprise applications, complex architectures
• README: View README

@objectstack/nextjs

Next.js Adapter — React metaframework.

• Use case: Full-stack React applications, App Router, Server Components
• README: View README

@objectstack/nuxt

Nuxt Adapter — Vue metaframework.

• Use case: Full-stack Vue applications
• README: View README

@objectstack/sveltekit

SvelteKit Adapter — Svelte metaframework.

• Use case: Full-stack Svelte applications
• README: View README

Developer Tools

@objectstack/cli

CLI Tool — Command-line interface for ObjectStack.

• Commands: serve, studio, doctor, migrate, deploy
• When to use: Development, deployment, project management
• README: View README

npx @objectstack/cli serve --dev

@objectstack/create-objectstack

Project Scaffolding — Create new ObjectStack projects.

• Templates: Minimal, CRM, Todo, E-commerce
• When to use: Start a new ObjectStack project
• README: View README

npx create-objectstack my-app

@objectstack/vscode-objectstack

VS Code Extension — IDE support for ObjectStack.

• Features: Syntax highlighting, autocomplete, validation for metadata files
• When to use: Enhanced development experience in VS Code
• README: View README

Utility Packages

@objectstack/types

Shared Type Utilities — Common TypeScript types and utilities.

• Exports: Type helpers, utility types, branded types
• 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 (e.g. apps/objectos/src/server.ts or any custom adapter) via kernel.use(...) and a host-side HostConfig.

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 (pseudocode — exact shape depends on adapter)
import { ObjectKernel } from '@objectstack/core';
import { createDriverPlugin } from '@objectstack/driver-turso';
import { createServiceAiPlugin } from '@objectstack/service-ai';

const kernel = new ObjectKernel();
await kernel.use(createDriverPlugin({ /* libSQL config */ }));
await kernel.use(createServiceAiPlugin({ /* model providers */ }));
await kernel.bootstrap();

For Traditional Web Apps

import { createDriverPlugin } from '@objectstack/driver-sql';
import { createAuthPlugin } from '@objectstack/plugin-auth';
import { createServiceQueuePlugin } from '@objectstack/service-queue';

await kernel.use(createDriverPlugin({ client: 'pg', /* … */ }));
await kernel.use(createAuthPlugin({ /* … */ }));
await kernel.use(createServiceQueuePlugin({ /* … */ }));

For Enterprise Applications

import { createSecurityPlugin } from '@objectstack/plugin-security';
import { createAuditPlugin } from '@objectstack/plugin-audit';
import { createServiceAnalyticsPlugin } from '@objectstack/service-analytics';

await kernel.use(createSecurityPlugin({ /* … */ }));
await kernel.use(createAuditPlugin({ /* … */ }));
await kernel.use(createServiceAnalyticsPlugin({ /* … */ }));

The exact factory names follow each package's README.md — they all return a plugin object compatible with kernel.use().

Next Steps

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