Skip to content

Latest commit

 

History

History
188 lines (157 loc) · 5.26 KB

bootstrap.md

File metadata and controls

188 lines (157 loc) · 5.26 KB

Platform — bootstrap examples and composition notes

Minimal Example

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

export default defineStack({
  manifest: {
    id: 'com.example.todo',
    version: '1.0.0',
    type: 'app',
    name: 'Todo Manager',
  },
  objects: [
    {
      name: 'task',
      label: 'Task',
      fields: {
        title:    Field.text({ required: true }),
        status:   Field.select({ options: [
          { label: 'Open', value: 'open' },
          { label: 'Done', value: 'done' },
        ], defaultValue: 'open' }),
        due_date: Field.date(),
      },
    },
  ],
});

Map Format (Key → Name)

All named collections support map format where the key becomes the name field:

export default defineStack({
  // Array format
  objects: [
    { name: 'task', fields: { title: Field.text() } },
  ],

  // Map format — preferred
  objects: {
    task: { fields: { title: Field.text() } },
    project: { fields: { name: Field.text() } },
  },
});

Barrel Import Pattern

// src/objects/index.ts
export { default as task } from './task.object';
export { default as project } from './project.object';

// objectstack.config.ts
import * as objects from './src/objects';
import * as apps from './src/apps';
import * as views from './src/views';
import * as flows from './src/flows';

export default defineStack({
  manifest: { id: 'com.example.pm', namespace: 'pm', version: '1.0.0', type: 'app', name: 'PM' },
  objects: Object.values(objects),
  apps: Object.values(apps),
  views: Object.values(views),
  flows: Object.values(flows),
});

Scaffolding Command

# Interactive — prompts for a name
npx create-objectstack

# Direct — skip prompts (blank is the default, and the only, template)
npx create-objectstack my-app

Plugin Loading Order Matters

Plugins initialize in registration order. Key dependencies:

Plugin Depends On Reason
ObjectQLPlugin (none) Core data engine, should load first
DriverPlugin (none) Registers driver service
AppPlugin ObjectQLPlugin Registers objects/metadata with engine
AuthPlugin ObjectQLPlugin Needs user/session objects
RESTPlugin ObjectQLPlugin, AppPlugin Generates routes from registered objects
AIServicePlugin ObjectQLPlugin, AppPlugin Needs metadata for tool generation. Cloud / EE only — @objectstack/service-ai moved to cloud (cloud ADR-0025); the open edition has no in-UI AI plugin and uses @objectstack/mcp (BYO-AI)

Programmatic Bootstrap (Without CLI)

import { Runtime, DriverPlugin, AppPlugin } from '@objectstack/runtime';
import { ObjectQLPlugin } from '@objectstack/objectql';
import { InMemoryDriver } from '@objectstack/driver-memory';
import appConfig from './objectstack.config';

const runtime = new Runtime();
runtime.use(new ObjectQLPlugin());
runtime.use(new DriverPlugin(new InMemoryDriver()));
runtime.use(new AppPlugin(appConfig));
await runtime.start();

const kernel = runtime.getKernel();
// kernel is now ready — use it with an adapter

Multi-App Composition

Host several apps in one runtime by registering an AppPlugin per app (packages/cli/src/commands/serve.ts). Each app contributes its objects under their globally unique name; use it directly in queries, hooks, formulas, and REST URLs.

composeStacks() (@objectstack/spec) merges stacks at authoring time, with objectConflict / manifest strategies. A suite (an app package plus module packages, one app each) composes with composeStacks(stacks, { manifest: 'preserve' }), which keeps each package's own id (examples/app-multi-package). A flat manifest ('last', the default, 'first' or an index) keeps one, so two or more apps under one app or module package id are refused (STACK_SINGLE_APP_VIOLATION, 422).

Complete Working Example

package.json:

{
  "name": "my-todo-app",
  "type": "module",
  "scripts": {
    "dev": "objectstack dev",
    "start": "objectstack start",
    "build": "objectstack build",
    "validate": "objectstack validate"
  },
  "dependencies": {
    "@objectstack/spec": "18.6.0",
    "@objectstack/runtime": "18.6.0",
    "@objectstack/driver-memory": "18.6.0",
    "@objectstack/plugin-hono-server": "18.6.0"
  },
  "devDependencies": {
    "@objectstack/cli": "18.6.0",
    "typescript": "^5.3.0"
  }
}

src/objects/task.object.ts — one ObjectSchema.create({ … }) call. Field types, indexes: and the rest of the object surface are objectstack-data's; the scaffolder's own note.object.ts is the shape to copy.

src/objects/index.ts:

export { default as task } from './task.object';

objectstack.config.ts:

import { defineStack } from '@objectstack/spec';
import * as objects from './src/objects';

export default defineStack({
  manifest: {
    id: 'com.example.todo',
    version: '1.0.0',
    type: 'app',
    name: 'Todo Manager',
  },
  objects: Object.values(objects),
});
# Run it
os dev --ui
# → Server at http://localhost:3000 (default port; dev auto-hops if taken)
# → REST API at http://localhost:3000/api
# → Console at http://localhost:3000/_console/