Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Getting Started

Before starting, note that Relay is typed from the ground up. The createRelay factory defined in libraries/relay/src/relay.ts lets you parametrize the configuration, step metadata, success payload, and error payload types before you register any steps. Type every shape first, then rely on StepSuccess and StepError to keep the runtime results discriminated so the compiler knows exactly when a step succeeded or failed. The rest of this guide walks you through that flow.

Declare your config

The first step is to define the TypeScript shapes that the relay will enforce. At a minimum, specify:

  • RelayConfig: extends the default Relay configuration.
  • RelayStepBase: carries metadata shared between every step.
  • RelayStepSuccess: represents the payload returned when a step resolves successfully.
  • RelayStepError: represents the payload returned when a step fails.
type RelayConfig = {};
type RelayStepBase = {
	label: string;
};
type RelayStepTransactionSuccess = {
	type: "transaction";
	txHash: string;
	blockNumber: number;
};
type RelayStepApiCallSuccess = {
	type: "apicall";
};
type RelayStepSuccess = RelayStepTransactionSuccess | RelayStepApiCallSuccess;
type RelayStepError = {
	message: string;
};

These types keep your configuration options, step metadata, success payloads, and error payloads explicit so the rest of your app consumes typed data. Everything is fully typed.

Instantiate the Relay and export helpers

With the types in place, call createRelay and pass the generics so the returned helpers stay typed across your app. Doing so wires the store with your StepSuccess and StepError payload shapes and makes it easy to reuse myRelay from any component.

type RelayConfig = {};
type RelayStepBase = {
	label: string;
};
type RelayStepTransactionSuccess = {
	type: "transaction";
	txHash: string;
	blockNumber: number;
};
type RelayStepApiCallSuccess = {
	type: "apicall";
};
type RelayStepSuccess = RelayStepTransactionSuccess | RelayStepApiCallSuccess;
type RelayStepError = {
	message: string;
};
 
const myRelay = createRelay<RelayConfig, StepBase, StepSuccess, StepError>("my-relay"); 
export { myRelay }; 

This gives you a singleton keyed by my-relay with your configurations.

Create the steps

Where you define your steps is flexible: you can build them inside a hook or in a standalone module, whichever fits your architecture. In most apps you will set them up while preparing the UI (typically in a hook).

Below we create three placeholder steps to demonstrate the shape.

app.tsx
const steps = [
	myRelay.createRelayStep({
		id: "id-0",
		label: "API call",
		fn: async () => {
			await new Promise((resolve) => setTimeout(resolve, 1000));
			return myRelay.StepSuccess({ type: "apicall" });
		},
	}),
	myRelay.createRelayStep({
		id: "id-1",
		label: "Send Tx",
		fn: async () => {
			await new Promise((resolve) => setTimeout(resolve, 1000));
			return myRelay.StepSuccess({
				type: "transaction",
				txHash: "0x",
				blockNumber: 100_000_000,
			});
		},
	}),
	myRelay.createRelayStep({
		id: "id-2",
		label: "API call",
		fn: async () => {
			await new Promise((resolve) => setTimeout(resolve, 1000));
			return myRelay.StepSuccess({ type: "apicall" });
		},
	}),
];

These step definitions now exist and are fully typed.

Initialize the Relay with the steps

Calling initialize stores the steps in memory so they are ready to fire and execute.

app.tsx
const App = () => {
	const { initialize } = myRelay.useRelay();
 
	return (
		<div className="flex gap-4">
			<div>
				<button
					type="button"
					className="bg-cyan-500/20 text-cyan-500 rounded px-2"
					onClick={() => { initialize(steps) }}
				>
					Initialize
				</button>
			</div>
		</div>
	);
};

Start the Relay

Starting the relay executes the initialized steps in order.

app.tsx
const App = () => {
	const { start } = myRelay.useRelay();
 
	return (
		<div className="flex gap-4">
			<div>
				<button
					type="button"
					className="bg-amber-500/20 text-amber-500 rounded px-2"
					onClick={() => { start() }}
				>
					Start
				</button>
			</div>
		</div>
	);
};

Observe

The final step is observing the relay state and inspecting each step’s status.

sidebar.tsx
const Sidebar = () => {
	const { stepsBase, stepsState } = myRelay.useRelay();
 
	return (
		<div>
			{stepsBase.map((item, index) => {
				const state = stepsState[index];
 
				return (
					<div className="flex gap-2" key={item.id}>
						<div>{item.label}</div>
 
						{(() => {
							if (state.status === "success") {
								const payload = state.payload;
 
								if (payload.type === "apicall") {
									return <div>Success</div>;
								}
 
								if (payload.type === "transaction") {
									return (
										<div className="flex gap-2">
											<div>{payload.txHash}</div>
											<div>{payload.blockNumber}</div>
										</div>
									);
								}
							}
 
							if (state.status === "error") {
								return <div>{state.payload.message}</div>;
							}
 
							return <div>{state.status}</div>;
						})()}
					</div>
				);
			})}
		</div>
	);
};

Because the steps share the metadata and payload types defined in libraries/relay/src/relay.ts, the entire pipeline stays strongly typed. The relay.initialize/relay.start pair wires the flow and begins execution. After that you can use relay.retry() to rerun a failed step or relay.next() to advance manually while keeping an eye on relay.stepsState for the live statuses.

Now your pipeline is wired: the typed store owns the state, your component creates typed steps, and the UI executes them through the Relay helpers.