Guide · By Danylo Pravda · Updated
Connect a React app to your backend with Beamline UI
Beamline UI provides React components and screens. Your app supplies the records, streams, sessions and saves. A backend connection has two directions: decoded data goes into props, and a person's action goes out through a callback. The component does not choose your API or store credentials.
The full data integration guide contains complete TypeScript files for a paged REST grid, React Query and SWR reads, WebSocket/SSE market snapshots, a form POST and a Next.js Server Component. Each example is compiled and rendered against built Beamline packages in a fresh consumer app. Its API is a local test fixture, so the result is evidence for the examples, not certification of a customer's backend.
Choose the boundary you already have
Scroll sideways to compare columns
| Your app has | Put the connection here | Give Beamline |
|---|---|---|
| A REST API | A fetch function and a hook in your app | Decoded records and request state |
| React Query or SWR | The app's existing query cache | Its data, loading and error values |
| A WebSocket or SSE stream | One subscription with cleanup and a data adapter | A new bounded snapshot when data changes |
| Next.js server-rendered pages | Fetch in the Server Component; keep handlers in a client file | Serializable records passed to the client view |
| An authenticated form endpoint | An awaited submit handler | Confirmed saved values or a rejected promise |
Start with one read
Use the REST example to map your response into the
data grid. Its columns are typed, record IDs are stable and a missing amount stays null.
A response with no records shows an empty state; a failed response shows an error. Neither is replaced by a made-up
zero. An aborted old request cannot overwrite the current page.
The example's data and total are an explicit contract you implement. An existing API can keep its own contract:
map its fields in the adapter, without changing the component. When the page works, reuse that adapter with
React Query or SWR if the app already uses either one.
Make writes report the server's result
For a form, return the request promise from the handler. Check the HTTP status and validate the response before showing success. The form POST example keeps the draft on rejection and uses the server's confirmed value on success. The Form component supplies the field and pending/error wiring; your server supplies validation and storage.
A grid edit is a different contract. DataGrid.onCellEdit tells your app what changed; it does not await a save or
manage rollback. Keep pending/error state in the app and update the grid's data with your chosen confirmed or
draft values. For an entire profile screen, Settings has an awaited onSave callback and
preserves continued edits; the profile notes explain it.
Verify a save by reading the stored record after reload. A success toast proves that the UI displayed a message.
Add live data without losing its meaning
The stream example connects either WebSocket or SSE to the same order book, price chart and grid. It validates complete snapshots, rejects out-of-order sequence numbers within a connection, bounds retained rows and candles, closes the connection on unmount, and labels old data when a connection stops delivering updates.
That contract matters: replacing a full snapshot is different from applying an exchange's delta feed. If your exchange sends deltas, preserve its sequencing rules and reload a snapshot after a gap. Put that logic in the adapter, not in several components. Candle times are UTC seconds, and missing prices must not become zero.
Keep large results on the server when needed
The grid virtualizes the rows it receives. It still sorts and filters those received rows in the browser. For server paging, use Pagination to request one page, disable local controls that would misrepresent a partial dataset, and label totals for the scope they actually cover. A cursor API does not need an invented page count. See pagination and large data.
Keep authentication separate from the screen
Clerk is the only authentication integration proven in Beamline's own service. beamline.io uses the kit's Auth block with Clerk. Auth.js, Supabase Auth, Firebase Auth, Auth0 and a custom session API are possible adapter patterns, explicitly untested here. A displayed sign-in state is not permission to read a record; server-side authorization must protect requests and subscriptions. The authentication section states the boundary and the stream-credential constraints.
Ask your agent for a connection you can verify
After connecting your agent, give it the endpoint contract, identity/permission rules and the screen's expected states. For example: “Install Beamline's data grid and pagination. Use our /api/deals page response. Keep unknown amounts unmeasured, show loading and failed requests separately, and verify page changes and saved records after reload. Use our existing authentication and query cache.”
The agent can choose and install the UI parts. Your API contract determines whether the connection is correct.