Skip to content
Text size
Text size

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.

  • Node.js 24 or later, with npm.
  • Protobuf compiler (protoc) on your path. Check with protoc --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-dart on your path. This guide was tested with protoc_plugin 25.0.0.
  • An internet connection for the initial package and runtime downloads.

Install the Dart plugin with:

Terminal window
dart pub global activate protoc_plugin 25.0.0

On macOS or Linux, include its executable directory on your path:

Terminal window
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.

Terminal window
npx --yes [email protected] my-nomos-app
cd my-nomos-app
npm install

This 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.

Terminal window
npm run compile
npm run typecheck

Compilation 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/.

Terminal window
npx githolon conformance

This 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:

Terminal window
npx githolon conformance --offline

For a machine-readable report, add --json. Failed checks return a nonzero exit code.

  • Package not found: check the package version and registry connection. The npm package names still use githolon.
  • Dart check fails: confirm dart --version and read the compiler’s diagnostic. Keep the Nomos package versions from the starter together.
  • Runtime acquisition fails: run conformance online first. --offline needs the runtime already cached.
  • Compile refuses an older cached runtime: the CLI can reuse ~/.holon/runtime from an earlier installation. On macOS or Linux, retry with a fresh temporary download using NOMOS_CANDIDATE_RUNTIME="$(mktemp -d)" npm run compile. This keeps the existing cache and workspace data intact.
  • Conformance fails after downloading: retain its --json report, including package versions and the failing check. A successful compile alone does not establish runtime behaviour.

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.