Project structure

Project structure

Mesh does not own your project. You choose where resource files live and where generated files go; Mesh reads the first and writes the second. This page proposes the starter template’s layout, using the todo-app project from Example: a todo list.

The layout

todo-app/
  mesh.config.ts
  package.json            "mx": { "contracts": "generated/mx-contracts.js" }
  resources/              .mx files (one resource per file)
    list.mx
    todo.mx
  generated/              written by `mesh build`, committed, guarded
    model.json
    index.ts              connect(), disconnect(), re-exports every action function and type
    schema.ts             Drizzle table definitions (adapter's build half)
    mx-contracts.js       composed contracts module for MX tooling (M6)
    todos/                one folder per `domain`; no domain: generated/ itself
      list.types.ts  list.actions.ts  list.validators.ts
      todo.types.ts  todo.actions.ts  todo.validators.ts
  migrations/             SQL from `mesh migrate generate`, committed
  extensions/             project-local extensions, if any (build entry + run-time entry)
  src/
    actor.ts              registers the actor type
    main.ts               the program

Resource files

One resource per .mx file, under the folder resources names in the configuration; nested folders are included. A configured glob or file list can select a subset instead. A file holds exactly one resource; two resources in one file is a build error.

Tag and attribute names follow Ash’s DSL, in kebab-case with the trailing ? dropped (ADR-0034). Every example is written in MX concise syntax, the indentation-based form (ADR-0041). The full list of tags is in the Resource file reference.

The generated tree

mesh build writes generated/ and you commit it. The reason is review: a resource file is a small declarative change, and the committed TypeScript beside it is what the program actually runs. A reviewer reads the diff of both together.

In this proposal, your program imports generated functions and types through generated/index.ts. It exports connect and disconnect and re-exports the resource modules.

The subfolder todos/ is named after the domain attribute on the resource. A resource with no domain has its files directly in generated/. Grouping by domain keeps one feature’s generated code in one folder.

Column names equal attribute names. Mesh does not transform names from camelCase to snake_case, so an attribute dueOn becomes a column dueOn. Drizzle quotes identifiers, so this works on both databases without a naming convention.

The guard. mesh build --check regenerates the tree in memory, writes nothing, and fails if the result differs from what is committed. It catches hand edits and stale trees. See Generated code and the guard.

Configuration

One file, mesh.config.ts, at the project root. It names the resource folder, the output folder, the data adapter and the enabled extensions. See Configuration.

package.json carries one extra key, "mx": { "contracts": "generated/mx-contracts.js" }. That points MX tooling at the composed contracts module, which mesh build writes: one self-contained module holding the tag contracts of core plus every enabled extension (ADR-0021). It arrives in M6; before that the contracts are composed in memory for the build only.

Migrations

migrations/ holds plain SQL files that mesh migrate generate writes and you commit. They are the record of how the database got to its current shape, and they are how another machine or another environment reaches it. Nothing is applied automatically; mesh migrate apply is explicit.

For a file-backed SQLite database in development, mesh db push is quicker. It is the same schema without a history, and it is a development tool.

Extensions

extensions/ holds project-local extensions. An extension has two entries: a build-time one, which contributes tags, transforms, verifiers, emitters and mesh subcommands through a manifest, and a run-time one, which supplies behaviour. The run-time entry follows the same import rule as @mesh/runtime: no compiler, no model, no MX, so a deployed program never carries the build pipeline.

First-party extensions are installed from npm instead, and are enabled by listing them in mesh.config.ts. @mesh/ext-policies is the one that exists in v1. See Extension host.

Your own code

src/ is yours. Mesh never reads it. In the example:

• src/actor.ts registers the actor type by module augmentation, so scope.actor is typed as whatever your application says a caller is.
• src/main.ts is the program: connect, call actions, disconnect.

Nothing in src/ must be named a particular way, and nothing in it is generated.

What to commit

Next

• Example: a todo list — the resources behind this layout.
• Configuration.
• Usage — the loop, including what the guard checks.