Use One from a framework-native application#

This recipe follows ParcelHub's framework-native Next/TypeScript Orders Desk while keeping its routes, components, state, styling, and runtime application-owned. The shortened TypeScript mirrors the current owning source; elided binding and presentation helpers remain illustrative end-product syntax.

1. Export the client projection#

one export contract-projection \
  --workspace systems/system-idl/examples/parcelhub \
  --build-report .one/build/parcelhub_orders_desk/host/dev/<revision>/build-report.json \
  --offline

Install the resulting receipted package through the application's ordinary package workflow. Package presence does not select a One provider or create an Experience realization claim.

2. Call One from the application-owned page#

import { OneClient, OrdersClient } from
  "@one-generated/parcelhub-orders-desk-client";

const transport = await OneClient.connect({ endpoint: window.location.origin });
const client = new OrdersClient(transport);
const result = await client.get({ customerId, orderId });

if (result.kind === "success") showOrder(result.value);
else if (result.kind === "domain_fault") showNotFound();
else showUnavailable();

Next owns routing, rendering, local state, styling, and component lifecycle. The generated client owns operation values and protocol behavior.

3. Submit a mutation without hiding uncertainty#

const result = await client.cancel(input);

switch (result.kind) {
  case "success": return showCancelled(result.value.orderId);
  case "domain_fault": return showDomainFault(result.fault);
  case "effect_commit_outcome_unknown": return showReconciliation();
  default: return showUnavailable(result);
}

The application does not auto-retry effect_commit_outcome_unknown or treat an HTTP response as the domain result.

4. Keep roots separate#

browser root -> public schemas, browser client, assets, client credential
Next server root -> server client, session bridge, framework runtime
Orders service root -> implementation, state capability, workload grant

This remains a framework-native application. To claim an exact Experience realization it must submit a separate admitted mapping with coverage and loss evidence.

Executable evidence#

ParcelHub's checked-in application declaration selects the Next/TypeScript profile, source closure, runtime values, readiness scenario, and exact TypeScript projection. Its application-owned page implements inspect, place, cancel, domain-fault presentation, duplicate-action prevention, and unknown-outcome guidance in operator language.

See applications and generate and use an SDK client.