CLI, keys, and errors | Ringroad Docs

ringroad-renderer ships a small binary (src/main.rs, clap) with three subcommands, useful for theme development without a running API.

`ringroad-renderer serve`

A stub-context preview server for iterating on themes:

cargo run -p ringroad-renderer -- serve --path themes --port 7502

Serves GET / (the configured theme’s preset index page) and GET /{slug}/{*page_key} with a stub StorefrontContext, enough to render and inspect most nodes. ?product= selects sample data.
Binds 0.0.0.0:port (default 7502).
Uses notify to watch the themes directory and rebuilds the Engine on every change, debounced 200 ms, edit a node, refresh, see it.

`ringroad-renderer build`

cargo run -p ringroad-renderer -- build --path themes/default --output dist

Loads the engine from the theme’s parent directory, then writes:

combined.css / combined.js, the theme’s full combined assets,
assets.json, the asset manifest,
processed assets/ (Jinja-rendered, copies otherwise).

Fails with ThemeNotFound when the directory isn’t a loaded theme.

`ringroad-renderer init`

cargo run -p ringroad-renderer -- init --name MyTheme --output themes/my-theme

Scaffolds a minimal theme: theme.json, layout/theme.jinja, templates/index.json, and empty nodes/, snippets/, locales/, assets/ directories, the starting skeleton for a new theme (see Theme from scratch).

Reserved config keys

src/keys.rs:

Constant	Value
`TEMPLATE_SETTINGS_KEY`	`@root:settings`
`TEMPLATE_HEADER_KEY`	`@root:header-group`
`TEMPLATE_FOOTER_KEY`	`@root:footer-group`
`make_group_key_string(group)`	`@root:{group}-group` (header/footer only)

These are the page_key values the API binary uses for the global-settings config and the two section groups in store_templates.

Errors

src/error.rs, a single crate-wide enum:

Variant	Carries
`NotFound`	,
`ThemeNotFound(String)`	theme slug
`SectionTypeNotFound(String)`	node type
`Template(String)`	message (template name / render error)
`Serialization(String)`	message
`Other(String)`	free-form

Result<T> is the crate-wide alias. Most render paths wrap template errors with the template name so failures are traceable to a file.

Test coverage

The tests/ suite defends the contracts end to end:

File	Contracts
`schema_tests.rs`	setting types, validation, defaults, color resolution
`section_tests.rs`	node resolution, rendering, slots, presets
`page_tests.rs`	full page renders, cache policies, template resolution
`engine_tests.rs`	engine construction, filters, fragment rendering
`integration_tests.rs`	end-to-end render flows with the fixture theme
`data_sources_tests.rs`	stub data sources, lazy metafield behavior
`asset_tests.rs`	CSS subsetting, combined builds, asset processing
`cli_tests.rs`	build/init outputs
`default_theme_smoke.rs`	renders the real `themes/default` theme

The fixture theme (tests/fixtures/themes/test-theme/) exercises the full settings taxonomy, including color_palette + color_scheme_group + active_scheme, and an “all-settings” node with 26 setting types.