Entities

A PRISM app has two ways to work with relational data:

1. defineEntity: a config-driven admin generator. It maps one entity to full CRUD screens, backed by Platform API procedures.
2. SQL queries: the framework's sql tagged template, for queries you write yourself.

defineEntity

defineEntity maps one entity to list / detail / new / edit screens and the matching CRUD, backed by Platform API tRPC procedures.

The read procedures are typed: list.proc and getById.proc only accept names from the kit's procedure catalog, so a typo there is a compile error. The response type of list.proc is also passed to the rows and total adapters. The crud.create, crud.update and crud.delete names are plain strings: check them yourself.

Configuration

Reads and writes go through the kit, which calls the Platform API itself: you do not write a client. The API address, tenant and site come from configureManage(...), called once in a module that every route imports for its side effect:

// src/lib/manage-setup.ts
import { configureManage } from "@bext-stack/manage/config";

configureManage({
  appId: "<app-id>",
  cmBase: "…",
  host: "…",
  origin: "…",
  tenantId: "…",
  siteId: "…",
});

Thin re-export

To publish a generated entity, re-export the kit's entity module from a route file, after importing the setup module:

// src/app/manage/posts/page.tsx
import "../../../lib/manage-setup";
export { loader, default } from "@bext-stack/manage/entities/posts";

An entity ships one module per screen it has (some entities have only a list):

Example: helpdesk knowledge base

The helpdesk knowledge-base "articles" entity is a defineEntity config wired to these procedures:

An excerpt of that config:

import { defineEntity } from "@bext-stack/manage/lib/entity";

export const helpdeskKbArticles = defineEntity({
  name: "article",
  namePlural: "articles",
  icon: "book-open",
  basePath: "/manage/helpdesk/knowledge-base",
  list: {
    proc: "helpdeskKb.getArticles",
    rows: (r) => (Array.isArray(r) ? r : []),
    total: (r) => (Array.isArray(r) ? r.length : 0),
    input: (q) => ({
      search: q.search || undefined,
      status: q.filters.status || undefined,
    }),
  },
  getById: { proc: "helpdeskKb.getArticleById" },
  crud: {
    create: "helpdeskKb.createArticle",
    update: "helpdeskKb.updateArticle",
    delete: "helpdeskKb.deleteArticle",
  },
  // columns, filters and form fields omitted
});

See Helpdesk.

SQL queries

For hand-written queries, the framework exports a tagged-template SQL helper:

import { sql, database } from "@bext-stack/framework";

const db = database("data.sqlite");
const posts = db.all(sql`SELECT id, title FROM posts WHERE author_id = ${authorId}`);

An interpolated array becomes a list of parameters, handy for IN (...). Fragments compose without breaking parameter numbering:

const rows = db.all(sql`
  SELECT id, title FROM ${sql.id("posts")}
  WHERE id IN (${ids})
  ${sql.if(authorId, sql`AND author_id = ${authorId}`)}
  ORDER BY created_at ${sql.raw(desc ? "DESC" : "ASC")}
`);

const conds = [sql`status = ${status}`, sql`author_id = ${authorId}`];
const count = db.get(sql`SELECT COUNT(*) AS n FROM posts WHERE ${sql.join(conds, " AND ")}`);

const { changes } = db.run(sql`UPDATE posts SET status = ${"archived"} WHERE id = ${id}`);

The createSdk client also offers sdk.db.all, sdk.db.get and sdk.db.exec with ? parameters (see the SDK Overview). These calls are asynchronous; exec returns { changes, lastInsertId }. Every parameter is sent as a string: numbers are stringified, and null or undefined becomes an empty string. Write NULL in the SQL text when you need a real null.

Where to next