Packbase web

The Packbase web client is wildbasehq/packbase-react-ui. It uses React, TypeScript, Vite, TanStack Router, TanStack Query, Clerk, the Packbase TypeScript SDK, Lingui, Tailwind CSS, Storybook, and a Cloudflare Worker.

Startup and ownership

src/main.tsx composes the application providers in this order: localisation, theme, motion, shared app UI, Clerk, Packbase SDK/query state, and the router. src/App.tsx then chooses among signed-out routes, server maintenance, initial profile failure, required new-user onboarding, and the authenticated desktop shell.

Use these locations:

Add or change a route

1. Put the file under src/routes using the existing TanStack file-route pattern.
2. Keep route-only helpers next to it with the repository’s ignored-prefix convention.
3. Reuse route and layout context rather than constructing another navigation model.
4. Let the router tooling regenerate src/routeTree.gen.ts.
5. Check direct navigation, browser history, modified clicks where links are involved, loading, not-found, and recoverable error states.

Add Packbase data to a screen

1. Check whether the published SDK already exposes the read or mutation.
2. Add or extend a typed hook in src/hooks/packbase.
3. Choose public, preferred, or authenticated client scope deliberately. Ordinary reads that can improve after sign-in normally use preferred; use the stricter scopes when the contract requires them.
4. Define the TanStack Query key and enabled conditions from the actual resource identity.
5. For a mutation, name the optimistic updates, rollback, invalidations, duplicate-submit protection, and retry behaviour.
6. Export the hook through src/hooks/use-packbase.ts.
7. Pass rendered data and callbacks into provider-free presentation components.

Do not add a second generic resource layer around TanStack Query, construct SDK clients inside features, or use an ad hoc fetch to avoid an SDK contract task.

The provider’s request wrapper may refresh a Clerk token and retry once after an authentication failure. If refresh cannot recover, it signs the browser session out. Preserve that bounded retry and recovery behaviour rather than adding feature-local token loops.

Build an interface state

Start from an existing shared primitive. Feature components own product meaning; shared primitives own reusable mechanics. Provide default, hover, pressed, focus, disabled or pending, selected, success, empty, and failure states as applicable.

For layout work, check narrow width, short height, long intrinsic content, keyboard navigation, 200% zoom, touch targets, dark and light themes, and reduced motion. A loading skeleton should reserve the eventual shape, and a later-page failure should not erase already loaded content.

Copy and localisation

User-facing copy uses Lingui macros. Supported catalog directories are en, it, and ja. After changing source copy:

bun run lingui:extract

Review the catalog diff; extraction is not translation. Do not place runtime schema strings directly into locale files to keep them from being cleaned—use the repository’s extraction anchors and schema-message mapping.

Stories and tests

Colocate unit tests as .test.ts or .test.tsx. Add provider-free stories for meaningful component states. Interactive or accessibility behaviour belongs in a story play test when it needs a browser surface. The full bun run check command runs lint, types, format verification, unit and Storybook tests, the app build, and the Storybook build.

→Frontend changesA repeatable Packbase web workflow for routes, components, SDK state, accessibility, localisation, and stories.