Getting started with Jumentix

Responsibility in context

• Owns: the public on-ramp for juniors adopting Jumentix (mental model + first journey)
• Stack: concepts / learning path (not a runtime package)
• Used with: @jumentix/cli-init factory generator, guides (REST, realtime, SPA/PWA), public packages hub
• Not responsible for: private workspace tooling docs (config-*, agent-registry, security-scanner)

What it is

Jumentix is a software factory framework: you describe business rules and API contracts once, then generate and run REST APIs, realtime channels, and offline clients from the same core. This page is the on-ramp for junior developers who have never used Jumentix before.

Why it exists

Product teams often rebuild the same plumbing — HTTP wiring, OpenAPI alignment, WebSocket handlers, IndexedDB sync — in every project. Jumentix gives you a repeatable path so you spend time on domain logic instead of adapter glue. This page gets you from zero to a verified first success in under 30 minutes.

Prerequisites

Install Bun if you do not have it yet:

curl -fsSL https://bun.sh/install | bash
bun --version

Prior reading (skim once, return when a term appears):

• Jumentix Overview
• Architecture

Glossary

Numbered steps

Step 1 — Install the toolchain (< 5 minutes)

1. Install Bun (see Prerequisites).
2. Confirm the version gate passes: bun --version.

Success check: the command exits 0 and prints a semver ≥ 1.4.2.

Step 2 — Pick your starting path (< 2 minutes)

Choose one path — do not try both on day one:

For product teams generating a workspace (recommended):

npx @jumentix/cli-init init my-app \
  --preset=users --non-interactive --mode=monolith \
  --http=express --db=sqlite --install

For teams that only need SDKs:

bun add @jumentix/cana @jumentix/sdk-rest-client

For contributors working in the full workspace:

cd Jumentix
bun install

Success check: factory path creates my-app/ with .jumentix/project.json; package path completes bun install without errors.

Step 3 — First success: factory init (< 10 minutes)

The public factory generator is @jumentix/cli-init. It writes a lean Bun workspace for one factory mode (monolith / services / hybrid / frontend) from a GenerationPlan (--preset=users, --from designer/OAS/catalog).

npx @jumentix/cli-init init demo \
  --preset=users --non-interactive --mode=hybrid --frontend \
  --http=express --db=sqlite --install
 
cd demo
npx @jumentix/cli-init doctor
ls apps          # core (+ frontend when hybrid)

What you should see:

• .jumentix/project.json — mode, plan, template cohort (not the retired service-profile.json)
• .jumentix/manifest.json — sha256 of generated files
• jumentix.init.json — answers for --config round-trips
• apps/* workspace packages ready for bun run dev|test|lint|build

Extend later with jumentix add domain|service|frontend, refresh templates with jumentix upgrade, and diagnose with jumentix doctor. Modes map to the service factory capabilities matrix (see also repository doc JUMENTIX-SERVICE-FACTORY-CAPABILITIES-MATRIX.md).

Success check: demo/.jumentix/project.json exists, doctor exits 0, and you can name the HTTP adapter folder under apps/.

Then open the REST API guide and call the generated service.

Step 4 — Learn the mental model (< 5 minutes)

Keep this picture visible while you read guides:

[ Adapters ]  Express / Fastify / Socket.IO / gRPC / IndexedDB (Cana)
      ↓
[ Application ] use-cases, ports
      ↓
[ Domain ] entities, rules, events

Three rules that prevent most junior mistakes:

1. Contracts first — OpenAPI / AsyncAPI / shared packages describe the shape before you wire handlers.
2. Adapters are replaceable — swap Express for Fastify without rewriting domain code.
3. Offline is first-class — @jumentix/cana is the IndexedDB adapter for PWAs; it is not the same as localStorage.

Step 5 — Touch Cana in the browser (< 10 minutes)

Before building a full offline PWA, confirm the docs toolchain works. Run the playground below — Run should return a green result, then Reset should restore the starting state.

### Getting started

```ts
const client = cana.createClient({
  name: dbName,
  schema: {
  version: 1,
  stores: [
    { name: 'categories', keyPath: 'id', indexes: [{ name: 'byName', keyPath: 'name', unique: true }] },
    {
      name: 'tasks',
      keyPath: 'id',
      indexes: [
        { name: 'byCategory', keyPath: 'categoryId' },
        { name: 'byCompleted', keyPath: 'completed' },
        { name: 'byUpdatedAt', keyPath: 'updatedAt' }
      ]
    }
  ]
}
});
await client.open();
await client.table('categories').add({
  id: 'work',
  name: 'Work',
  color: '#2563eb',
  createdAt: Date.now(),
  updatedAt: Date.now()
});
await client.table('tasks').add({
  id: 'task-1',
  title: 'Write the Cana tutorial',
  categoryId: 'work',
  completed: false,
  priority: 'high',
  createdAt: Date.now(),
  updatedAt: Date.now()
});
return {
  backend: client.backend,
  category: await client.table('categories').get('work'),
  task: await client.table('tasks').get('task-1')
};
```

const client = cana.createClient({
  name: dbName,
  schema: {
  version: 1,
  stores: [
    { name: 'categories', keyPath: 'id', indexes: [{ name: 'byName', keyPath: 'name', unique: true }] },
    {
      name: 'tasks',
      keyPath: 'id',
      indexes: [
        { name: 'byCategory', keyPath: 'categoryId' },
        { name: 'byCompleted', keyPath: 'completed' },
        { name: 'byUpdatedAt', keyPath: 'updatedAt' }
      ]
    }
  ]
}
});
await client.open();
await client.table('categories').add({
  id: 'work',
  name: 'Work',
  color: '#2563eb',
  createdAt: Date.now(),
  updatedAt: Date.now()
});
await client.table('tasks').add({
  id: 'task-1',
  title: 'Write the Cana tutorial',
  categoryId: 'work',
  completed: false,
  priority: 'high',
  createdAt: Date.now(),
  updatedAt: Date.now()
});
return {
  backend: client.backend,
  category: await client.table('categories').get('work'),
  task: await client.table('tasks').get('task-1')
};

Success check: playground Run completes without errors; you see IndexedDB records created in the output panel.

Step 6 — Core workflows (this week)

Complete these guides in order when you need each capability:

Step 7 — Full surface (when you need lookup, not tutorials)

Examples

Minimal REST client call (static)

Inject the OpenAPI document in the browser — do not load specs with Node fs:

const client = api.createMockClient();
const result = await client.request({ method: 'GET', path: '/health' });
console.log(result.status, result.body);

See the interactive version on Create a REST API.

Offline record with Cana (static)

const client = await cana.open({ name: 'my-app', version: 1 });
await client.put('tasks', { id: '1', title: 'Hello Jumentix' });
const task = await client.get('tasks', '1');
console.log(task.title);

Use the Cana playground in Step 5 to run this pattern live.

Common errors

Junior checklist (“I can …”)

• Install Bun 1.4.2+ and confirm bun --version.
• Explain the adapter → application → domain layers using the diagram above.
• Run jumentix init (or npx @jumentix/cli-init init) and locate .jumentix/project.json.
• Run the Cana playground (Run green, Reset restores state).
• Name the difference between OpenAPI (REST) and AsyncAPI (realtime).
• Open the REST guide and know it is my next hands-on task.
• Find package docs and playgrounds at /docs/jumentix/packages.

Next step

Go to Create a REST API and complete the hello-world path end to end — that is the default second page in the learning journey.