Usage

Usage

This page is the loop you will work in every day: change a resource file, build, let the type checker tell you what broke, run the program. It assumes the todo-app project from Installation and the resources from Example: a todo list.

1. Write a resource file

Copy the complete resources/list.mx, resources/todo.mx and src/actor.ts files from Example: a todo list. Keep the actions, relationships and policies, not just the attributes: step 3 calls the create actions on both resources and the pending read on todo.

A resource is one .mx file: Marko syntax, read by MX. Mesh chooses the tag names; the syntax is MX’s. The file is indentation-based, with no angle brackets.

MX does not run any of this. It reads the file as a static tree of tags and attributes, so every value Mesh needs without executing code must be a literal. A bare identifier is a build error, not an import.

2. Build

bunx mesh build

The build reads every .mx file under the configured resources folder, checks the structure, builds a model, transforms it, verifies it, compiles the expressions and writes the generated tree. It also writes the database schema file, from the build half of the data adapter.

What the build writes for you to commit (using this spec’s proposed layout; see Project structure):

What the build checks and refuses:

• a tag, attribute or value the vocabulary does not allow, at the file, line and column;
• a tag the contracts accept but the compiler does not implement yet, naming the milestone that will;
• accept naming an attribute the resource does not have;
• two resources with the same name, or two resources in one file;
• a free variable in an expression: a translatable expression may use only its declared parameters and the registered functions;
• a capability the configured adapter does not declare.

Nothing is silently dropped and nothing silently downgraded. The roadmap calls this its second principle: no silent fallback.

3. Call an action from TypeScript

An action is a generated function. The signature is always (input, scope), and both arguments are required. There is no server and no route: calling the function is the whole interface (ADR-0005).

Create the development database first with bunx mesh db push, then save this as src/main.ts and run bun run src/main.ts:

import { connect, disconnect, createList, createTodo, pendingTodo } from "../generated";
import { alice } from "./actor";

await connect({ file: "todo.db" });

const list = await createList({ name: "Groceries" }, { actor: alice });
await createTodo(
  { title: "Buy milk", listId: list.id },
  { actor: alice },
);

console.log(await pendingTodo({}, { actor: alice }));

await disconnect();

{ actor, context } is the scope: who is calling, plus anything else the call needs. It is a plain argument on every call, never ambient, so a test can pass a different actor in one line (ADR-0007). Calling actions has the full signatures.

4. Change the resource, rebuild

Add this line inside the attributes block of resources/todo.mx. This is an insertion, not a complete resource file:

+    attribute="dueOn" type="datetime"

bunx mesh build

The build rewrites the generated tree. Look at what changed:

git diff generated/

The diff is the reviewable record of what your resource change means: a new column in schema.ts, a new field in the Todo type, a new optional key in every action input that accepts it. Commit the generated tree with the resource file. It is committed, not ignored, so a reviewer reads the same code you run and a git diff shows behaviour changes.

5. Let the type checker tell you what broke

Generated code is ordinary TypeScript, so tsc --noEmit (or your editor) reads it. This is the point of writing the behaviour into the generated handlers instead of into a shared engine: the error you get names your own generated function.

If you renamed an attribute, every call that passed the old name is a type error. If you removed one from accept, every call that still passes it is a type error, and a call that slips past the type checker is rejected at run time with InvalidInputError: an unknown field is an error, never dropped.

6. Update the database

During development, push the schema straight to the database:

bunx mesh db push

For anything you keep, generate a migration instead:

bunx mesh migrate generate
bunx mesh migrate apply

mesh migrate generate compares the old model with the new one and refuses a destructive or ambiguous change (dropping a column, changing its type, renaming it, making an optional column required) unless you name it:

bunx mesh migrate generate --allow drop:todo.dueOn

Migrations are plain SQL files in migrations/, and they are committed. Nothing is ever applied automatically. See Command-line tool.

7. Check before you commit

bunx mesh build --check

This runs the whole build again, regenerates in memory, writes nothing, and fails if the result differs from what is committed. It catches a hand edit to a generated file, and it catches a resource file you changed without rebuilding.

Two builds of the same input give the same bytes: the output comes from templates through a pinned formatter. That is what makes the check meaningful.

In your own project, add "test": "bunx mesh build --check && bun test" to package.json’s scripts object, then run bun run test. That checks the generated tree before running your tests. Mesh’s own repository has no continuous integration until the MX packages are published (ADR-0031), so a skipped run is invisible.

Next

• Calling actions — signatures, the scope, filters, load, and the errors an action throws.
• Configuration — what is in mesh.config.ts.
• Command-line tool — every mesh command.