Docs/Developers

Modules in code

What a module is in locosdk, how an app installs one (the spread in schema.ts is the install), the recipes behind the portal's one click install, and the catalogue.

A module is a name shared by up to three halves of locosdk, plus a manifest. It ships inside the sdk, carries an integer version, and holds a contract that the app's gate runs. The business view of the same modules: Modules.

The halves stay in their tiers, so a browser bundle never imports a server half.

The spread is the install#

// schema.ts
import { auth, crm, defineSchema, numbering, quotes, quotesSeries, text } from 'locosdk/schema'

const staff = '@request.auth.id != ""'

export const numbers = numbering({ readRule: staff, timeZone: 'Europe/Paris', series: { ...quotesSeries() } })

export const schema = defineSchema({
    users: auth({ fields: { name: text() } }),
    ...numbers.collections,
    ...crm({ users: 'users', listRule: staff, createRule: staff, deleteRule: null }).collections,
    ...quotes({ users: 'users', listRule: staff, createRule: staff, deleteRule: null, crm: { companies: 'companies', contacts: 'contacts', deals: 'deals' }, numbers }).collections,
})

// server.ts, before app.serve()
mintNumbers(app)
bindQuotes(app)

// src/client.ts and src/main.tsx: the screens, mounted by the app
export const crmUi = new CrmScreens(installOf(schema, 'crm'), { db, session })
// in the pages of the AppRouter
...crmUi.pages({ group: navGroup('customers') })

• Rules are the module's law. What the app decides arrives through rule slots (listRule, createRule, deleteRule, and the like) filled with the app's own snippets. A slot left null is superusers only.
• Links between modules are typed options. quotes({ crm: … }) names crm's collections in this app, stock({ site }) scopes stock by the sites install. A typo in a target fails the typecheck.
• One numbering per app. Every numbered module joins its series into the one numbering(...) install and takes it as numbers.
• defineSchema refuses a module collection missing or replaced by an app spec, a module installed twice, a key the module did not name, and a field its snippets read that the app lacks. Each refusal names the way out.
• serve() refuses an app that holds a module with a server half it never bound.
• Each module's collections are compiled against the composed schema at boot, so a bad slot fails the boot, not the first request.

Customize through the options#

A module grows through its extension points: rule slots, names (its collections under the app's words), fields (app fields on a module collection, typed into the records), the app's own hooks chained around the module's, the screens' props and slots, and string overlays through uiI18n.configure. A client need that no point covers becomes a new point in the sdk, so every app keeps getting the module's fixes through its sdk update and its gate.

Versions and migrations#

• A module's shape is its current collections. Its steps are deltas between two of its versions, recorded as <module>@<n> in _migrations.
• A module none of whose collections exists yet (a fresh database, or a module just added to a live app) is built from its current shape, and every step is recorded as applied.
• At boot: each module's unrecorded steps, then the app's migration files, then the sync.
• Rows a new database needs (the default Admin profile of rights) are the module's defaults, written once, only into an empty collection.

The golo commands#

Recipes: the one click install#

A module that the portal installs carries a recipe: the deterministic edits its install makes from the owner's answers, never a model. It asks a few typed questions (an auth collection, a rule, some of the app's collections, a choice, another module to link), then edits schema.ts (imports, a declared install, the entries, the accounts collection when the module adds fields to it), server.ts (the bind call before app.serve()), src/client.ts and src/main.tsx (the screens and their menu entries), and adds a new: line under ## Unreleased of CHANGELOG.md in the app's language.

The portal shows the diff, then applies that exact plan: the dev app stops, the files are written, golo gate runs, the dev app starts again on its new tables, and the change is committed and pushed. A red gate or a failed boot restores every file and the database as they were. Uninstall is the inverse, found from the recipe's own import names; it is refused while another module requires this one, or while the app's own code still names its screens.

The catalogue#

Each module has its own page in the agent kit, inside the app: node_modules/locosdk/agent/api/modules/<name>.md.

A module with no recipe is wired by an agent, on a request.

This page as markdown