Package Overview

ObjectStack is organized into 42 packages across multiple categories. This guide provides a complete overview of each package, its purpose, and when to use it.

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
• When to use: Import types, schemas, and builder functions (defineObject, defineView, defineFlow, etc.)
• Documentation: Protocol Reference

import { Data, UI, defineObject, defineView } from '@objectstack/spec';

@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

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 { DriverMemory } 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 { DriverSQL } from '@objectstack/driver-sql';
const driver = DriverSQL.configure({
  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 { DriverTurso } from '@objectstack/driver-turso';
const driver = DriverTurso.configure({
  url: 'libsql://mydb-username.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-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

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
• When to use: Multi-user applications with access control requirements
• 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-setup

Setup Plugin — First-run setup wizard.

• Features: Initial configuration, sample data, guided setup
• When to use: New project initialization
• 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

For New Projects

import { defineStack } from '@objectstack/spec';
import { DriverTurso } from '@objectstack/driver-turso'; // Edge-first
import { ServiceAI } from '@objectstack/service-ai'; // AI features

const stack = defineStack({
  driver: DriverTurso.configure({ /* ... */ }),
  services: [ServiceAI.configure({ /* ... */ })],
});

For Traditional Web Apps

import { DriverSQL } from '@objectstack/driver-sql'; // PostgreSQL/MySQL
import { PluginAuth } from '@objectstack/plugin-auth'; // Authentication
import { ServiceQueue } from '@objectstack/service-queue'; // Background jobs

const stack = defineStack({
  driver: DriverSQL.configure({ client: 'pg', /* ... */ }),
  plugins: [PluginAuth.configure({ /* ... */ })],
  services: [ServiceQueue.configure({ /* ... */ })],
});

For Enterprise Applications

import { PluginSecurity } from '@objectstack/plugin-security'; // RBAC
import { PluginAudit } from '@objectstack/plugin-audit'; // Compliance
import { ServiceAnalytics } from '@objectstack/service-analytics'; // BI

const stack = defineStack({
  driver: DriverSQL.configure({ /* PostgreSQL */ }),
  plugins: [
    PluginSecurity.configure({ /* ... */ }),
    PluginAudit.configure({ /* ... */ }),
  ],
  services: [
    ServiceAnalytics.configure({ /* ... */ }),
    ServiceI18n.configure({ /* ... */ }),
  ],
});

Next Steps

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