Quickstart
Create a project from the published starter, compile it and check the installed toolchain. The starter models an estate and its assets. It does not include a user interface.
Prerequisites
Section titled “Prerequisites”- Node.js 24 or later, with npm.
- Protobuf compiler (
protoc) on your path. Check withprotoc --version. - Dart 3.5 or later on your path to check the generated Dart client. Flutter includes Dart.
- The Dart Protobuf plugin, with
protoc-gen-darton your path. This guide was tested withprotoc_plugin25.0.0. - An internet connection for the initial package and runtime downloads.
Install the Dart plugin with:
dart pub global activate protoc_plugin 25.0.0On macOS or Linux, include its executable directory on your path:
export PATH="$PATH:$HOME/.pub-cache/bin"You do not need a Nomos account or access to a source repository. The task example uses only TypeScript and does not need Dart or its plugin.
Create a project
Section titled “Create a project”cd my-nomos-appnpm installThis guide pins a tested version. The starter selects matching versions of the compiler, CLI and test harness. Keep the generated package-lock.json with your project.
Compile and check the domain
Section titled “Compile and check the domain”npm run compilenpm run typecheckCompilation produces the domain package and generated clients. Type checking should finish with no errors.
The files you edit are:
| File | Purpose |
|---|---|
domains/estate.ts |
Defines estates, assets and the commissionAsset action |
nomos.project.ts |
Selects the domain modules and generated client packages |
nomos.application.ts |
Describes how the compiled domain is composed into an application |
The main outputs are:
| Output | Purpose |
|---|---|
build/my-nomos-app.law.usdz |
Compiled domain package used by the runtime |
build/my-nomos-app.reception.mjs |
Generated TypeScript client |
build/my-nomos-app.reception.d.mts |
TypeScript client types |
build/application/ |
Generated Dart packages |
build/my-nomos-app.application.usda |
Compiled application composition |
Compilation also creates nomos.identity.usda. Keep this file in version control: it preserves declaration identities when you change the model. Do not edit generated files in build/.
Check the installed runtime
Section titled “Check the installed runtime”npx githolon conformanceThis runs a separate, bundled example through the local runtime. It checks a write and read, an expected rejection, persisted history and a cold restart. It checks the installed packages; it does not test the business behaviour of your estate domain.
The command should end with:
PASS — installed Node stack conforms.The first run may download verified runtime files. Once cached, you can check the offline path:
npx githolon conformance --offlineFor a machine-readable report, add --json. Failed checks return a nonzero exit code.
If a step fails
Section titled “If a step fails”- Package not found: check the package version and registry connection. The npm package names still use
githolon. - Dart check fails: confirm
dart --versionand read the compiler’s diagnostic. Keep the Nomos package versions from the starter together. - Runtime acquisition fails: run conformance online first.
--offlineneeds the runtime already cached. - Compile refuses an older cached runtime: the CLI can reuse
~/.holon/runtimefrom an earlier installation. On macOS or Linux, retry with a fresh temporary download usingNOMOS_CANDIDATE_RUNTIME="$(mktemp -d)" npm run compile. This keeps the existing cache and workspace data intact. - Conformance fails after downloading: retain its
--jsonreport, including package versions and the failing check. A successful compile alone does not establish runtime behaviour.
Run an application example
Section titled “Run an application example”Continue with Build a task app for a small domain and runnable tests. It includes a local write/read journey and a two-device synchronisation test, using the same published toolchain.