@cargo-ai/app-sdk

The SDK for building Cargo Hosting apps — a Vite + React + refine bundle that gives you working Cargo OAuth sign-in, a typed @cargo-ai/api client (via useCargoApi()), a shadcn/ui-styled theme, and the standard refine view scaffolds — so Claude Code (or you) can spend tokens on the screens that actually matter.

Install

npm install @cargo-ai/app-sdk @cargo-ai/api @auth0/auth0-react react react-dom react-router-dom

Use it

// src/App.tsx
import { CargoRefineApp, CargoSiderLayout } from "@cargo-ai/app-sdk";
import { Routes, Route } from "react-router-dom";
import { Inbox } from "lucide-react";

import { LeadInbox } from "./pages/LeadInbox";

const resources = [
  {
    name: "leads",
    list: "/",
    meta: { label: "Leads", icon: <Inbox className="h-4 w-4" /> },
  },
];

export const App = () => (
  <CargoRefineApp resources={resources}>
    <CargoSiderLayout title="Lead Console">
      <Routes>
        <Route path="/" element={<LeadInbox />} />
      </Routes>
    </CargoSiderLayout>
  </CargoRefineApp>
);

What ships

• <CargoRefineApp> — Cargo OAuth + refine + router + Cargo API context, all wired.
• CargoAuthProvider — refine AuthProvider that gates the app on app_metadata.workspaceUuids matching the build-time VITE_CARGO_WORKSPACE_UUID.
• Hooks: useCargoApi() for the typed API client, useCargoAnalytics() for pageviews + custom events.
• Layouts: <CargoSiderLayout>, <CargoEmpty>, <CargoErrorBoundary>, <CargoUserMenu>, <CargoWorkspaceBadge>.
• View wrappers: <List>, <Show>, <Edit>, <Create>, <DataTable>.
• Cargo domain composites in src/components/domain/<domain>/: read-only icons / badges / cards over the typed @cargo-ai/api domain types — agents, workflows + run statuses, datasets/models, segments, integrations/connectors, members (plus a self-fetching <MemberSelect>).
• shadcn/ui primitives copy-pasted from the registry into src/components/ui/: forms (<Button>, <Input>, <Textarea>, <Label>, <Checkbox>, <RadioGroup>, <Switch>, <Slider>, <Select>, <Toggle>, <ToggleGroup>, <Calendar>), surfaces (<Card>, <Sheet>, <Dialog>, <AlertDialog>, <Popover>, <HoverCard>, <Tooltip>, <Separator>, <ScrollArea>, <Collapsible>, <Accordion>), nav (<Tabs>, <Breadcrumb>, <Pagination>, <NavigationMenu>, <DropdownMenu>, <ContextMenu>, <Menubar>, <Command>), display (<Table>, <Badge>, <Avatar>, <Skeleton>, <Progress>, <Spinner>, <Alert>, <Toaster>), and charts (<ChartContainer> + helpers, wraps recharts).
• Tailwind preset (@cargo-ai/app-sdk/tailwind-preset) + base CSS (@cargo-ai/app-sdk/styles.css).

Env vars

Cargo Hosting bakes these into the bundle automatically. For local dev run cargo-ai hosting app env <appUuid> > .env.local:

VITE_CARGO_OAUTH_DOMAIN=...
VITE_CARGO_OAUTH_CLIENT_ID=...
VITE_CARGO_OAUTH_AUDIENCE=...
VITE_CARGO_API_URL=https://api.getcargo.io
VITE_CARGO_WORKSPACE_UUID=...
VITE_CARGO_APP_UUID=...
VITE_APP_BASE_PATH=/

Next.js apps read the same vars with a NEXT_PUBLIC_ prefix (NEXT_PUBLIC_CARGO_API_URL, …); Cargo Hosting injects both.

Adding shadcn primitives

The pack ships shadcn/ui components copy-pasted into src/components/ui/. Pull a new one in via the wired-up CLI:

npm run -w @cargo-ai/app-sdk shadcn:add -- <component>
# e.g.
npm run -w @cargo-ai/app-sdk shadcn:add -- tooltip

That runs shadcn@latest add against this package's components.json, then a post-processor (scripts/shadcn-postprocess.mjs) rewrites the CLI's @/ alias imports to relative ./…/foo.js paths and strips "use client" directives so the file fits the SDK's NodeNext / Vite shape. After it finishes:

1. Add the new exports to src/index.ts by hand (the CLI doesn't touch barrels).
2. If the component pulls in CSS variables we don't already define (e.g. --chart-1 for chart), add them to styles.css.

To compare a local primitive against the upstream shadcn source:

npm run -w @cargo-ai/app-sdk shadcn:diff -- <component>

Do not run npx shadcn init in this package. components.json, styles.css, and tailwind.config.ts are hand-curated; init would overwrite them. Only add / diff are safe.

Reference

• SKILL.md — the prompt Claude Code reads when scaffolding apps.
• @cargo-ai/api — typed Cargo API client.
• docs.getcargo.ai/api-reference/introduction — REST reference.