Skip to content

The dev domain watcher

The dev domain watcher watches a folder of domain files and applies every change to a running dev server. You edit YAML in your editor and save; the server updates the domains a moment later. No clicks in the UI, no API calls, no restarts.

  • You develop a domain in files under version control.
  • You want reviewable changes instead of editor clicks.
  • You work with AI coding agents that write domain files.
  • A dev server you own. The watcher never runs in production; the server refuses to start it there.
  • A folder the server can read. Add the dev.domain_watch section to your dev configuration:
dev:
domain_watch:
path: ./dev
poll_ms: 500
documents: preserve
Key Default Meaning
path required The folder with one subfolder per domain.
poll_ms 500 How often the folder is polled.
documents preserve preserve keeps documents you created in the app. discard rebuilds everything from the files on every change.

Each direct subfolder of the watch path holds one domain bundle:

dev/
└── acme.facet-domain/
├── bundle.yml
├── domain.yml
└── doctypes/
└── acme.Project.yml

The subfolder name is free; the domain’s name comes from bundle.yml:

format_version: 2
source_domain: acme
exported_at: "2026-11-13T09:00:00Z"
facet_version: 0.1.0

domain.yml carries the domain document — a content block with the label and description, and an empty meta. Each file in doctypes/ is one doctype definition:

content:
doctype: Project
domain: acme
schema_version: 1
aggregate_root: true
label: Project
display_name: "{{ name }}"
fields:
name:
type: string
required: true
meta:
parent_id: acme

Save any file. Within a poll cycle or two, the server applies the folder: it reads the bundle, replaces the definitions, and reports one line per domain in the server log. A bundle added while the server runs is picked up on the next poll. The watcher waits for quiet, so a save that lands as several file writes applies once.

The server runs the domain check after every sync and logs the issue count. For the full report, read the dev report route:

Terminal window
curl -k -H "Authorization: Bearer $FACET_API_KEY" \
"https://facet.localhost:3443/Api/dev/check-report?domain=acme"

A sync that fails validation logs the exact field errors, and the domain keeps its previous state until the next good save.

With preserve, documents you created in the app survive a sync, and bundled sample documents fill only missing rows. With discard, every sync rebuilds the domain from the files, which suits tests with fixed sample data.

You add a priority field to the Project doctype:

priority:
type: string
title: Priority

You save. The log line reports the acme sync with its import counters. You open the running app, and the Project form already shows the new field. Because the mode is preserve, the projects you created during testing are still there.

Nothing happens when I save.

The section may be missing from the config, the path may not exist, or the subfolder may lack bundle.yml. A subfolder without that file is ignored.

The sync fails on every save.

Read the logged field errors; they name the file and the field. The domain stays on its previous state, so you can fix the file with the app still running.

The same domain appears twice.

Two subfolders declare the same domain name. Keep one; the log names both.