Skip to content

quick-start.mdx

Latest commit

 

History

History
181 lines (142 loc) · 6.1 KB

quick-start.mdx

File metadata and controls

181 lines (142 loc) · 6.1 KB
Raw
title Developer Guide
description Learn to build enterprise applications with the ObjectStack Protocol

Developer Guide

This guide teaches you how to build real applications using the ObjectStack Protocol. Each section is hands-on, with code examples derived from the HotCRM reference app.

**New to ObjectStack?** Start with the [Example Apps](/docs/getting-started/examples) to see working code, or read the [Introduction](/docs/getting-started) for the architecture overview.

Quick Start

Create a project

npx @objectstack/cli init my-app
cd my-app

Add AI skills to your editor

Install the ObjectStack skill bundle so your AI assistant (Claude Code, Copilot, Cursor, …) knows the protocol's schemas and conventions:

npx skills add objectstack-ai/framework --all

Re-run the same command any time to update — the bundle is versioned as one unit. See the AI Skills Reference for the full catalog.

Scaffolding with `npm create objectstack@latest` runs this step automatically.

Define your first object

The scaffolded project includes a sample object. Open src/objects/my_app.ts:

import { ObjectSchema, Field } from '@objectstack/spec/data';

const myApp = ObjectSchema.create({
  name: 'my_app',
  label: 'My App',
  ownership: 'own',
  fields: {
    name: Field.text({ label: 'Name', required: true }),
    description: Field.textarea({ label: 'Description' }),
    status: Field.select({
      label: 'Status',
      options: [
        { label: 'Draft', value: 'draft' },
        { label: 'Active', value: 'active' },
        { label: 'Archived', value: 'archived' },
      ],
      defaultValue: 'draft',
    }),
  },
});

export default myApp;
This is the same metadata that powers the REST API, Studio editors, and the MCP tools exposed to AI agents — define it once, and ObjectStack derives the rest.

Launch the Studio

os studio

Open http://localhost:3000/_studio/ to browse your objects, test the REST API, and inspect metadata. The server automatically provides:

  • ObjectQL Engine — Query layer with CRUD operations
  • InMemory Driver — Zero-config data storage for development
  • Hono HTTP Server — REST API at /api/v1/{object}
  • Console UI — Admin interface at /_studio/

Add more metadata

os g object customer       # Generate a new object
os g action approve        # Generate an action
os g flow onboarding       # Generate an automation flow

Validate, build, and run

os validate        # Check schema correctness
os compile         # Generate production artifact → dist/objectstack.json
os start           # Boot from the compiled artifact (no config file needed)

The compiled dist/objectstack.json is a portable, self-describing deployment unit — see CLI → Source vs Artifact for details.

Learning Path

Follow these guides in order for the best experience:

Project Structure

A typical ObjectStack application (generated by os init):

my-app/
├── objectstack.config.ts     # App manifest + metadata wiring
├── package.json
├── tsconfig.json
├── src/
│   ├── objects/              # Data models (required)
│   │   ├── index.ts          # Barrel export
│   │   └── my_app.ts         # Object definition
│   ├── actions/              # Buttons, batch operations
│   ├── flows/                # Automation logic
│   ├── apps/                 # Navigation definitions
│   ├── dashboards/           # Analytics dashboards
│   ├── agents/               # AI agents
│   └── rag/                  # RAG pipelines
└── test/                     # Tests

File naming conventions:

  • Object files: {name}.object.ts or {name}.ts (one object per file)
  • Action files: {name}.actions.ts
  • Flow files: {name}.flow.ts
  • Barrel exports: Each directory has an index.ts that re-exports everything

Key Concepts

Concept Protocol You Define ObjectStack Provides
Data Model ObjectQL Objects, Fields, Validation CRUD APIs, database schema, type safety
User Interface ObjectUI Views, Apps, Dashboards React components, navigation, responsive layout
Business Logic Automation Flows, Workflows, Triggers Event handlers, approval chains, scheduled jobs
Access Control Security Profiles, Permissions, Sharing Middleware, RLS policies, field masking
Intelligence AI Agents, RAG, Models Chat interfaces, search indexes, predictions

Next Steps