The `ril` Instance

The ril instance is the heart of every RilayKit application. It serves as a central configuration hub for all your form and workflow configurations, providing type safety and component reusability across your entire application.

Core Responsibilities

The ril instance has two primary roles:

1. 🏗️ Component Registry: Stores your component configurations and custom renderers
2. 🏭 Builder Factory: Creates type-safe form and workflow builders that inherit its configuration

Creating and Configuring

You create an instance by calling ril.create() and then chain configuration methods to it.

import { ril } from '@rilaykit/core';
import { MyTextInput } from '@/components/MyTextInput';
import { myRowRenderer, mySubmitButtonRenderer, myBodyRenderer } from '@/renderers';

export const rilay = ril
  .create()
  // Register a component type named 'text'
  .addComponent('text', {
    name: 'Text Input',
    renderer: MyTextInput,
  })
  // Configure all renderers at once
  .configure({
    bodyRenderer: myBodyRenderer,
    rowRenderer: myRowRenderer,
    submitButtonRenderer: mySubmitButtonRenderer,
  });

This configured rilay instance is now ready to be used to create builders.

Management API

The ril instance is not just a write-only configuration object. It also provides a rich API for managing and inspecting its state, which can be useful for debugging, testing, or building developer tools.

Component Management

You can dynamically manage the component registry.

• getComponent(id: string): Retrieves a component's configuration.
• getAllComponents(): Returns an array of all registered components.
• hasComponent(id: string): Checks for the existence of a component type.
• removeComponent(id: string): Removes a component from the registry.
• clear(): Removes all registered components.

// Check if a 'text' component is registered
if (rilay.hasComponent('text')) {
  console.log('Text component is ready.');
}

// Get all component names
const componentNames = rilay.getAllComponents().map(c => c.name);
// -> ['Text Input']

Factory Methods

The ril instance provides convenient factory methods for creating builders:

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

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

Introspection & Debugging

Two methods are particularly useful for understanding the state of your configuration.

getStats()

The .getStats() method returns a snapshot of the current configuration, including the number of components and which custom renderers have been set.

const stats = rilay.getStats();
console.log(stats);

/* Output:
{
  total: 1,
  byType: { text: 1 },
  hasCustomRenderers: {
    row: true,
    body: false,
    submitButton: false,
    field: false,
    stepper: false,
    workflowNextButton: false,
    workflowPreviousButton: false,
    workflowSkipButton: false
  }
}
*/

validate()

The .validate() method performs an internal check of your configuration to find common errors, like duplicate component IDs or components without a renderer.

const errors = rilay.validate();

if (errors.length > 0) {
  console.error('Rilay configuration errors:', errors);
}