Drift & sync-types

npx flare sync-types [--check] [--force]

re-renders every derived file — tables, relations, routes, clients, validators, the registry, the schema index — from the resource descriptors, which stay the source of truth throughout.

How it decides what to do

Every generated block carries a checksum in its start marker (// generated:start hash=<12 hex>), a sha256 of the block’s content (ignoring CRLF and trailing whitespace differences). Comparing that hash against the current content of the block gives one of six statuses per file:

Status	Meaning
missing	The file doesn’t exist yet — it’s created.
identical	Nothing to do.
outdated	The descriptor changed since this block was written — it’s rewritten.
untracked	Current content has no checksum yet — one is added, content unchanged.
drift	The block no longer matches its checksum — it was edited by hand. Skipped and reported (exit code 1). Rewrite it with --force.
unmarked	A hand-written file sits at a path a generated file would occupy. Never touched, reported as a conflict.

Orphans

A file whose header says Generated by flare gen resource X, where X isn’t part of the current plan any more (the resource was removed, or its table/slug was renamed), is reported as an orphan.

Migration hints

When the content of a table changed — not just its checksum — the report points you at generating a migration next (flare gen migration <name> --from-schema).

--check, for CI

flare sync-types --check changes nothing and exits 1 if anything would change or needs attention. Run it in CI to catch a descriptor edited without regenerating, or a generated file edited by hand and forgotten.

Formatters and generated blocks

Reformatting a generated block (a different quote style, wrapped lines) counts as drift, because the checksum is on the block’s content. Either exclude generated blocks from your formatter’s scope, or re-run sync-types --force after formatting.

Descriptors are the source, not a target

sync-types reads the descriptors and never rewrites them, so editing a descriptor is not reported as drift; it is how you change a resource.

The descriptor’s fields block is still a tracked generated block for gen resource: re-running gen resource <Name> --fields "..." rewrites it through the same checksum check. If the block is unchanged since it was generated it is replaced; if you’ve hand-edited it, gen resource refuses (edit the descriptor directly and run gen resource <Name> or sync-types instead), and --force overrides. Everything outside the fields block is left alone. See the codegen overwrite contract.