Bitfield Docs

An app surface is the part your user sees. It should read named data, render every state, and send named requests. It should not import package storage details.

A founder adds a Customers screen. The screen needs a list, a loading state, an empty state, and one action: archive a customer.

Read

The surface asks for a stable input name and renders loading, error, empty, and success states.

→

Render

The user sees concrete product data: customers, messages, tasks, rooms, invoices, or whatever your product owns.

→

Act

The surface sends a small request to a target instead of mutating local files by hand.

Surface contract

Piece	Surface owns	Surface does not own
Reads	Which data name it needs and how to render each state	Storage layout or package admission
Actions	Button intent, payload shape, pending/error/success UI	Target execution details
Layout	Local component structure inside the surface	Global navigation and device/account placement
Copy	User-facing words for the product moment	Private setup details

Minimal shape

import { sendRequestToBitfieldTarget, useBitfieldData } from '@bitfield/runtime-kit';

export function CustomersSurface() {
  const customers = useBitfieldData('customers.list');

  if (customers.loading) return <p>Loading customers...</p>;
  if (customers.error) return <p>Customers could not load.</p>;
  if (!customers.data?.length) return <p>No customers yet.</p>;

  return (
    <ul>
      {customers.data.map((customer) => (
        <li key={customer.id}>
          <span>{customer.name}</span>
          <button
            type="button"
            onClick={() =>
              sendRequestToBitfieldTarget('customers.archive', { customerId: customer.id })
            }
          >
            Archive
          </button>
        </li>
      ))}
    </ul>
  );
}

The screen should render a real product list, survive loading and error states, and send one named product action without importing Bitfield storage or runtime setup.

What not to do

// Bad shape: the screen is trying to become the package loader.
const rawPackageFile = await fetch('/some-package-file.json');
const rows = JSON.parse(await rawPackageFile.text());

The surface should not parse package material. Package admission and named data reads belong in Runtime Kit, not app components.

Common failures

Symptom	Cause	Fix
The component crashes before data arrives	It renders only the success path	Add loading, error, empty, and success states
The screen imports or parses package file names	The surface is bypassing named data reads	Read through `useBitfieldData(...)`
Every button sends a vague command	The action reply shape is not product-shaped	Use a named target like `customers.archive`
The UI cannot show success or failure	The request result is ignored	Render pending, success, and failure feedback

Verify

Check	Passes when
Loading path	The screen shows a visible loading state before data arrives
Error path	The screen shows a visible error state when the read fails
Empty path	The screen explains what the user sees when no records exist
Success path	The screen renders product data, not storage vocabulary
Request path	The button calls a named target with a small payload

Use Package authoring to create the package file that can feed this surface. Use Runtime Kit API for the exact public function contracts.

Build a product

Activation

App surfaces

Surface contract

Minimal shape

What not to do

Common failures

Verify

Next

​Surface contract

​Minimal shape

​What not to do

​Common failures

​Verify

​Next

Surface contract

Minimal shape

What not to do

Common failures

Verify

Next