Build a Chakra application

HyperflowApp is the fastest way to add the complete Hyperflow experience to a Chakra application.

It provides the default app shell and Hyperflow routes. You can add your own pages and navigation without recreating client setup, routing, or real-time session behavior.

Complete Installation first. It installs the Chakra package, configures the Vite plugin, and connects your first HyperflowApp to the runtime.

What HyperflowApp includes

HyperflowApp includes:

• App shell: sidebar, top bar, and global notifications.
• Hyperflow pages: sessions, library, and settings.
• Application behavior: client setup, routing, authentication, and live session synchronization.

HyperflowApp always mounts its default toaster. When routes is omitted, it also registers the default route set shown below.

Customize HyperflowApp

HyperflowApp accepts props for configuring the runtime connection, extending the application, and replacing parts of the default Chakra setup:

The examples below cover the most common changes: adding, replacing, and ordering routes; adding navigation; and providing an initialization fallback.

Add, replace, and order routes

Pass routes to add pages, replace a default page, or both. A route with the same path as a default route replaces it; paths are compared without leading or trailing slashes. The routes you provide keep their array order and appear after any default routes you did not replace. Pass navItems to show links in the default sidebar.

import { HyperflowApp } from '@hyperflow/chakra-ui'
import type { HyperflowRoute, NavItem } from '@hyperflow/react'

function ReportsPage() {
  return <h1>Reports</h1>
}

function NewSessionPage() {
  return <h1>Start a project</h1>
}

const routes: HyperflowRoute[] = [
  { path: 'reports', component: ReportsPage },
  { path: 'sessions/new', component: NewSessionPage },
]

const navItems: NavItem[] = [
  { path: '/reports', label: 'Reports' },
]

export function App() {
  return (
    <HyperflowApp
      config={{
        apiUrl: 'https://runtime.example.com/api/v1',
        wsUrl: 'wss://runtime.example.com/api/v1/ws',
      }}
      routes={routes}
      navItems={navItems}
    />
  )
}

Replace the example URLs with the values provided for your environment. For a same-origin setup, use { apiUrl: '/api/v1', wsUrl: '/api/v1/ws' }.

To replace every default page, provide a route for each default path in the order you want. Any default path that you omit keeps its built-in page and position before your supplied routes. The system paths /login and /runtime-reload remain reserved and cannot be replaced through routes.

Show an initialization fallback

Pass fallback when the app needs to show its own loading UI while the Hyperflow client initializes. It is rendered only during initialization; it does not replace a session page or an error state.

import { HyperflowApp } from '@hyperflow/chakra-ui'

export function App() {
  return (
    <HyperflowApp
      config={{ apiUrl: '/api/v1', wsUrl: '/api/v1/ws' }}
      fallback={<p>Loading Hyperflow…</p>}
    />
  )
}

For the remaining HyperflowApp props, see the HyperflowApp reference. To customize the default application frame, see App shell.

Next steps

• Use Theme and tokens to change colors, spacing, and other visual defaults.
• Browse Components to understand the supplied Composer, Timeline, and HITL surfaces.
• Use Component overrides to replace a documented part of a supplied component.