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: guides (REST, realtime, SPA/PWA), public packages hub, apps hubs
• Not responsible for: private workspace tooling docs (config-*, agent-registry, cli-init, 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.3.13.

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

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

For product teams consuming published packages:

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

For contributors working in the full workspace:

cd Jumentix
bun install

Success check: bun install completes without errors; node_modules exists.

Step 3 — Open the reference backend (< 10 minutes)

Private bootstrap tooling is not documented on this public site. For your first backend, study the reference app already in the monorepo:

cd apps/backend-template
bun install
# follow scripts in that app's package.json / README for local run

Then open the REST API guide and reproduce the hello path against that template.

Success check: you can locate the HTTP adapter + a use-case folder inside apps/backend-template and open the REST guide next.

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 — First success: touch Cana in the browser (< 10 minutes)

Before building a full API, 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.3.13+ and confirm bun --version.
• Explain the adapter → application → domain layers using the diagram above.
• Scaffold or open a Jumentix service and locate .jumentix/service-profile.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.