@trueclara/parser

CLI usage, output policy, upload flow, and failure handling for the static Next.js route graph.

@trueclara/parser is the build-time source of truth for the TrueClara route graph.

Command

Run it from the Next.js app root:

Terminal

npx @trueclara/parser . --pretty -o trueclara-graph.json

Useful flags:

Flag	Purpose
`--pretty`	Formats JSON for review and upload scripts.
`--verbose`	Prints parser warnings to stderr.
`-o <file>`	Writes JSON to a file instead of stdout.

Upload

Upload the full parser output:

Terminal
curl -X POST https://api.trueclara.com/v1/static-graphs \
  -H "Content-Type: application/json" \
  -H "X-Trueclara-Project-Key: $TRUECLARA_PROJECT_KEY" \
  --data-binary @trueclara-graph.json

Do not trim the output to route paths. TrueClara needs the complete graph for Map, path matching, deploy diffs, observation context, and setup health.

Output expectations

Parser output should be deterministic for the same commit. Route ids, edges, and warnings should not depend on the machine running the command.

At minimum, a valid upload includes:

schema_version.
routes.
Route patterns for App Router or Pages Router files.
Parser warnings when static analysis cannot confidently resolve a feature.

Failure policy

Fail setup when the parser cannot produce a graph. If graph upload is missing or incomplete, runtime traffic may not match route patterns and observations may be weak.

For CI deploy attribution, fail on parser hard errors. A release with no graph is less useful than a release with a clear CI failure.