@arc-dev/client-react

Beautiful React hooks and components for the Arc Registry. Makes it incredibly easy to run Arcs with automatic input handling, state management, and clean component patterns.

Installation

npm install @arc-dev/client-react
# or
pnpm add @arc-dev/client-react
# or
yarn add @arc-dev/client-react

Quick Start

1. Wrap your app with ArcProvider

import { ArcProvider } from "@arc-dev/client-react";

function App() {
  return (
    <ArcProvider config={{ baseUrl: "https://arc-registry.example.com" }}>
      <YourApp />
    </ArcProvider>
  );
}

2. Use the useArc hook to run an Arc

import { useArc } from "@arc-dev/client-react";

function MyComponent() {
  const [state, { run, resume, reset }] = useArc("my-arc");

  const handleStart = () => {
    run({ initialValue: "Hello" });
  };

  const handleProvideInput = (input: string) => {
    resume(input);
  };

  // Arc completed successfully
  if (state.isCompleted) {
    return (
      <div>
        <h2>Result</h2>
        <pre>{JSON.stringify(state.finalState, null, 2)}</pre>
        <button onClick={reset}>Run Again</button>
      </div>
    );
  }

  // Arc is paused and waiting for input
  if (state.isPaused) {
    return (
      <div>
        <h2>Arc needs your input</h2>
        <p>Current state: {JSON.stringify(state.currentState)}</p>
        <InputForm onSubmit={handleProvideInput} />
      </div>
    );
  }

  // Arc is running
  if (state.isRunning) {
    return <Spinner text="Arc is running..." />;
  }

  // Error occurred
  if (state.error) {
    return (
      <div>
        <h2>Error</h2>
        <p>{state.error.message}</p>
        <button onClick={reset}>Try Again</button>
      </div>
    );
  }

  // Initial state - ready to start
  return <button onClick={handleStart}>Start Arc</button>;
}

API Reference

ArcProvider

Provider component that makes the Arc client available to all child components.

<ArcProvider
  config={{
    baseUrl: "https://arc-registry.example.com",
    apiKey: "your-api-key",
    timeout: 30000,
  }}
>
  <App />
</ArcProvider>

Props:

• config?: ArcClientConfig - Configuration for the Arc client
• client?: ArcClient - Optional pre-configured client instance

useArc(arcId, options)

Main hook for running an Arc with automatic state management and input handling.

Parameters:

• arcId: string - The ID of the Arc to run
• options?: UseArcOptions - Optional callbacks and configuration

Returns: [state, actions]

State:

{
  isRunning: boolean;
  isPaused: boolean;
  isCompleted: boolean;
  error: Error | null;
  sessionId: string | null;
  finalState: State | null;
  finalContext: Context | null;
  currentState: State | null;
  currentContext: Context | null;
  events: ArcEvent[];
}

Actions:

{
  run: (initialState?: Partial<State>) => Promise<void>;
  resume: (input: any) => Promise<void>;
  reset: () => void;
}

useArcList(autoLoad?)

Hook for listing available Arcs from the registry.

function ArcList() {
  const { arcs, isLoading, error, reload } = useArcList();

  if (isLoading) return <Spinner />;
  if (error) return <Error error={error} />;

  return (
    <div>
      <button onClick={reload}>Reload</button>
      <ul>
        {arcs.map((arc) => (
          <li key={arc.id}>
            <strong>{arc.id}</strong>: {arc.description}
          </li>
        ))}
      </ul>
    </div>
  );
}

Parameters:

• autoLoad?: boolean - Whether to automatically load the list on mount (default: true)

Returns:

{
  arcs: ArcCapability[];
  isLoading: boolean;
  error: Error | null;
  reload: () => Promise<void>;
}

useArcClient()

Hook to access the Arc client directly from context.

function CustomComponent() {
  const client = useArcClient();

  const handleCustomOperation = async () => {
    const metadata = await client.metadata("my-arc");
    console.log("Models used:", metadata.models);
  };

  return <button onClick={handleCustomOperation}>Get Metadata</button>;
}

Advanced Usage

With Event Callbacks

function EventLogger() {
  const [state, { run }] = useArc("my-arc", {
    onEvent: (event) => {
      console.log("Event:", event.type, event);
    },
    onComplete: (finalState, finalContext) => {
      console.log("Completed with state:", finalState);
    },
    onPause: (sessionId, state, context) => {
      console.log("Paused at session:", sessionId);
    },
    onError: (error) => {
      console.error("Error:", error);
    },
  });

  return <button onClick={() => run()}>Run Arc</button>;
}

Multiple Input Handling

The hook automatically handles Arcs that pause multiple times for input:

function MultiStepForm() {
  const [state, { run, resume }] = useArc("multi-step-arc");
  const [userInput, setUserInput] = useState("");

  const handleSubmitInput = () => {
    resume(userInput);
    setUserInput("");
  };

  if (state.isPaused) {
    return (
      <div>
        <h2>
          Step {state.events.filter((e) => e.type === "node-paused").length}
        </h2>
        <input
          value={userInput}
          onChange={(e) => setUserInput(e.target.value)}
          placeholder="Enter your input"
        />
        <button onClick={handleSubmitInput}>Continue</button>
      </div>
    );
  }

  if (state.isCompleted) {
    return <div>All done! {JSON.stringify(state.finalState)}</div>;
  }

  return <button onClick={() => run()}>Start Multi-Step Arc</button>;
}

Streaming Output

function StreamingOutput() {
  const [output, setOutput] = useState("");

  const [state, { run }] = useArc("streaming-arc", {
    onEvent: (event) => {
      if (event.type === "node-output-delta") {
        setOutput((prev) => prev + (event.delta || event.chunk || ""));
      }
    },
  });

  return (
    <div>
      <button onClick={() => run()}>Start</button>
      <pre>{output}</pre>
    </div>
  );
}

TypeScript Support

The hook is fully typed with generics:

interface MyArcState {
  text: string;
  result?: string;
}

interface MyArcContext {
  model: string;
  tokens: number;
}

function TypedComponent() {
  const [state, { run }] = useArc<MyArcState, MyArcContext>("my-arc");

  useEffect(() => {
    if (state.finalState) {
      // TypeScript knows finalState has 'text' and 'result' properties
      console.log(state.finalState.result);
    }
  }, [state.finalState]);

  return <button onClick={() => run({ text: "Hello" })}>Run</button>;
}

Examples

See the examples directory for complete working examples including:

• Basic Arc execution
• Multi-step forms with input handling
• Streaming output display
• Error handling patterns
• Event logging

License

Apache-2.0 - Copyright 2025 ARC PLATFORM LTD