The `ril` Instance

Understanding the central configuration hub of RilayKit - the foundation of type-safe forms.

The ril instance is RilayKit's central catalog: it registers components, tools, and message parts, and creates type-safe form and flow builders that inherit its configuration.

Create one shared instance and export it from a central file (e.g. lib/rilay.ts).

Creating and Configuring

Call ril.create() and chain registrations. Every method is immutable — it returns a new instance, so keep the final result of the chain.

lib/rilay.ts

import { ril } from 'rilaykit';
import { TextInput } from '@/components/TextInput';

export const rilay = ril
  .create()
  // Register a component type named 'text'
  .component('text', {
    name: 'Text Input',
    renderer: TextInput,
  })
  // Register an agent tool and a message-part renderer (optional)
  .tool('search_flights', { description: 'Search flights', inputSchema: flightSchema })
  .part('text', { renderer: TextPart });

A component entry accepts name, description, renderer, propsSchema (Standard Schema, validated via validateProps), defaultProps, validation, meta, and replace (allow overwriting — otherwise a duplicate id throws).

Two more chaining methods:

use(plugin) — applies a RilayPlugin (a function that registers entries and returns the extended instance).
renderers({ components, tools, parts }) — attaches or overrides renderers on already-registered entries; schemas and metadata are preserved.

Builder Methods

With the all-in-one rilaykit package, the instance creates builders directly:

const myForm = rilay.form('my-form')
  .add({ type: 'text', props: { label: 'Name' } });

const myWorkflow = rilay.flow('my-workflow', 'My Workflow')
  .step({ title: 'Step 1', formConfig: myForm });

.form(formId?) — equivalent to form.create(rilay, formId)
.flow(workflowId?, name?, description?) — equivalent to flow.create(rilay, workflowId, name, description)

With the modular packages (@rilaykit/forms, @rilaykit/workflow), use form.create(rilay) and flow.create(rilay) instead.

Catalog API

Method	Returns
`getComponent(id)` / `getTool(name)` / `getPart(type)`	The entry, or `undefined`
`getAllComponents()` / `getAllTools()` / `getAllParts()`	All entries of that kind
`hasComponent(id)`	`boolean`
`validateProps(type, props)`	Success/failure result against the component's `propsSchema`
`removeComponent(id)`	New instance without the component
`clear()`	New instance with an empty catalog
`clone()`	Copy of the instance

Introspection & Debugging

`getStats()`

Entry counts by kind:

rilay.getStats();
// { total: 3, components: 1, tools: 1, parts: 1 }

`validate()` and `validateAsync()`

validate() returns an array of error strings (e.g. duplicate component types) — empty means valid. validateAsync() additionally reports warnings such as renderer-less components, and throws a ValidationError when errors are found.