Use @usefractal/frac/web

This guide shows you how to use @usefractal/frac/web without @usefractal/frac/server to add React hooks and utilities to your views.

Prerequisites

You should already have:

A working MCP server backend (in any technology)
Node.js 24+

Install

Add frac to your project:

pnpm add @usefractal/frac

Package overview

@usefractal/frac/web provides React hooks and utilities for building advanced Apps:

State Management

useToolInfo: Get initial tool input, output and metadata
useViewState: Persist state across view renders

User Interface

useLayout: Get the current user layout and visual environment information
useDisplayMode: Get and request view display mode changes
useRequestModal: Open a modal portaled outside of the view iframe
useUser: Get the session-stable user information (locale and userAgent)

Actions

useCallTool: Call tools from within a view
useOpenExternal: Open external links
useSendFollowUpMessage: Send a follow-up message in the conversation
useFiles: Upload and download files

Others

useAppsSdkContext: Low-level hook to subscribe to window.openai state values
generateHelpers: Generate typed helpers for your views (requires @usefractal/frac/server)

Each hook is documented in the API Reference section in the sidebar.

Basic example

Here’s a simple view using frac hooks:

import { useToolInfo } from "@usefractal/frac/web";

export default function MyView() {
  const toolInfo = useToolInfo();

  if (toolInfo.isPending) {
    return <div>Loading...</div>;
  }

  if (toolInfo.isSuccess) {
    return (
      <div>
        <h2>Results</h2>
        <pre>{JSON.stringify(toolInfo.output.structuredContent, null, 2)}</pre>
      </div>
    );
  }

  return <div>No results</div>;
}

Type safety without server

If you’re not using @usefractal/frac/server, you won’t get automatic type inference. You can still add types manually:

import { useToolInfo } from "@usefractal/frac/web";

interface MyToolInput {
  query: string;
  limit?: number;
}

export default function MyView() {
  const toolInfo = useToolInfo<MyToolInput>();

  // toolInfo.input is now typed as MyToolInput
  console.log(toolInfo.input.query);

  return <div>View content</div>;
}

Learn more

To learn more about how to build an App, please read the Core Concepts and Interaction Model sections below.

Learn the fundamentals of MCP servers and Apps

Understand how tools, views, and the model communicate

End-to-end type inference from server to view