World in a Pie site: work in progress
← Back to Library

@wip/react

lib ·  frontend devs
reacthookstanstack-queryclient-librarywip-react

@wip/react

What it is. @wip/react is the React-hooks layer over @wip/client, built on TanStack Query v5 (@tanstack/react-query). It exposes one read hook (useQuery-based) or mutation hook (useMutation-based) per WIP operation across terminologies/terms (def-store), templates (template-store), documents (document-store), files, registry/namespaces, and the reporting layer, plus a hierarchical query-key factory (wipKeys), per-domain default stale times (STALE_TIMES), a brand-attribution component (WipFooter), and two hooks built on top of the primitives (useFormSchema, useBulkImport). Callers are frontend devs building the UI of a WIP-backed app. (package.json: "description": "React hooks for WIP client (TanStack Query)"; src/index.ts export groups.)

Install & import. Package @wip/react, version 0.18.0, "private": true (package.json). No npm publishConfig is present in scope — the package is consumed as a workspace/file dependency, matching README.md's own install snippet:

{
  "dependencies": {
    "@wip/client": "file:../../libs/wip-client",
    "@wip/react": "file:../../libs/wip-react",
    "@tanstack/react-query": "^5.0.0",
    "react": "^18.0.0 || ^19.0.0"
  }
}

Entry point per package.json exports: ESM ./dist/index.js (types ./dist/index.d.ts), CJS ./dist/index.cjs (types ./dist/index.d.cts); built by tsup (tsup.config.ts: entry: ['src/index.ts'], format: ['esm','cjs'], dts: true). react, react-dom, @tanstack/react-query, and @wip/client are declared external in the build (tsup.config.ts:12) and are peerDependencies in package.json — they are not bundled and must be installed by the consumer. Primary import:

import { WipProvider, useWipClient, useDocuments, useCreateDocument } from '@wip/react'

node >=18.0.0 (package.json engines).

⚠ Scope note applying to every entry below: parameter/return types imported from @wip/client (BulkResultItem, BulkResponse, WipBulkItemError, every *Request/*Response type, Namespace, Template, Document, Term, Terminology, FormField, BulkImportProgress, etc.) are named here exactly as imported, but their field-level shape is defined in @wip/client, which is outside this doc's source_scope (libs/wip-react only). Field-level detail for those types belongs in the @wip/client library doc — see "See also".

Core API

Grouped in the order src/index.ts groups them (Provider → Brand component → key/stale-time utilities → read hooks by domain → write hooks by domain → specialized hooks).

Provider & client access

WipProvider({ client, children })

useWipClient()

Brand-attribution component

WipFooter(props: WipFooterProps)

Cache & stale-time utilities

wipKeys

STALE_TIMES

Terminologies & terms (read)

useTerminologies(params?, options?)

useTerminology(id, options?)

useTerms(terminologyId, params?, options?)

useTerm(id, options?)

Templates (read)

useTemplates(params?, options?)

useTemplate(id, options?)

useTemplateByValue(value, options?)

Documents (read)

useDocuments(params?, options?)

useDocument(id, options?)

useQueryDocuments(query, options?)

useTableView(templateId, params?, options?)

useDocumentVersions(id, options?)

useDocumentRelationships(documentId, params?, options?)

useTraverseDocuments(documentId, params?, options?)

Files (read)

useFiles(params?, options?)

useFile(id, options?)

useDownloadUrl(id, options?)

Registry & namespaces (read)

useNamespaces(options?)

useRegistrySearch(params, options?)

Reporting & batch sync (read)

useReportQuery(sql, params?, options?)

useIntegrityCheck(params?, options?)

useActivity(params?, options?)

useSyncStatus(options?)

useBatchJobs(options?)

useBatchJob(jobId, options?)

Reporting & batch sync (write)

useTriggerBatchSyncAll(options?)

useTriggerBatchSync(options?)

useTriggerTerminologySync(options?) / useTriggerTermSync(options?) / useTriggerTermRelationSync(options?)

useCancelBatchJob(options?)

useClearCompletedJobs(options?)

Terminology mutations

useCreateTerminology(options?)

useUpdateTerminology(options?)

useDeleteTerminology(options?)

Term mutations

useCreateTerm(terminologyId, namespace, options?)

useUpdateTerm(options?)

useDeprecateTerm(options?)

useDeleteTerm(terminologyId, options?)

Template mutations

useCreateTemplate(options?)

useUpdateTemplate(options?)

useDeleteTemplate(options?)

useActivateTemplate(options?)

useReactivateTemplate(options?)

useAddEdgeTypeEndpoints(options?)

Document mutations

useCreateDocument(options?)

useCreateDocuments(options?)

useUpdateDocument(options?)

useUpdateDocuments(options?)

useDeleteDocument(options?)

useArchiveDocument(options?)

File mutations

useUploadFile(options?)

useUpdateFileMetadata(options?)

useDeleteFile(options?)

useDeleteFiles(options?)

useHardDeleteFile(options?)

Term-relation mutations

Term-relations are the term-ontology edges (is_a, part_of, ...) — a distinct concept from the document-to-document relationship documents surfaced by useDocumentRelationships/useTraverseDocuments above. Per source comment, the platform renamed this surface in WIP commit 2eeb872; @wip/react picked up the rename with no backward-compat alias (src/hooks/use-mutations.ts:484-491).

useCreateTermRelations(options?)

useDeleteTermRelations(options?)

Namespace mutations

useCreateNamespace(options?)

useUpdateNamespace(options?)

useArchiveNamespace(options?)

useRestoreNamespace(options?)

useDeleteNamespace(options?)

Registry-entry mutations

useAddSynonym(options?)

useRemoveSynonym(options?)

useMergeEntries(options?)

useDeactivateEntry(options?)

Specialized hooks

useFormSchema(templateValue, options?)

useBulkImport(options)

Usage patterns

1. Provider setup, then a read + a write. Wrap the tree with both QueryClientProvider (TanStack) and WipProvider; useWipClient() throws outside WipProvider.

const queryClient = new QueryClient()
const wipClient = createWipClient({ baseUrl: '', auth: { type: 'api-key', key: 'dev_master_key_for_testing' } })

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <WipProvider client={wipClient}>
        <MyComponent />
      </WipProvider>
    </QueryClientProvider>
  )
}

function MyComponent() {
  const { data } = useTerminologies({ status: 'active' })
  const createDoc = useCreateDocument()
  return (
    <button onClick={() => createDoc.mutate({ template_id: 'TPL-1', data: { name: 'Test' } })}>
      Create Document
    </button>
  )
}

(README.md:60-105)

2. Template-driven document form. useFormSchema + useTemplateByValue + useCreateDocument — the canonical flow for rendering a form from a template and writing back a matching document.

function DocumentForm({ templateValue }: { templateValue: string }) {
  const { data: fields } = useFormSchema(templateValue)
  const { data: template } = useTemplateByValue(templateValue)
  const createDoc = useCreateDocument()

  const handleSubmit = (formData: Record<string, unknown>) => {
    if (!template) return
    createDoc.mutate({ template_id: template.template_id, data: formData })
  }
  if (!fields) return <div>Loading...</div>
  return <DynamicForm fields={fields} onSubmit={handleSubmit} />
}

(README.md:761-782)

3. Bulk import with progress tracking. useBulkImport wraps any bulk writeFn (e.g. client.defStore.createTerms) with automatic batching and a live progress object.

const { mutate, isPending, progress } = useBulkImport({
  writeFn: (batch) => client.defStore.createTerms(terminologyId, batch),
  batchSize: 100,
  continueOnError: true,
  invalidateKeys: wipKeys.terms.all,
})
mutate(terms)
// progress.processed / progress.total / progress.succeeded / progress.failed

(README.md:552-589; hook mechanics from src/hooks/use-bulk-import.ts)

Gotchas

See also

Generated from real source code, not hand-written — see the WIP Technical Library.