Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
description: "Use the web app's standard libraries and house helpers: ts-pattern, neverthrow, TanStack Query, solid-primitives, Kobalte wrappers, and friends." paths: - "apps/web/" - "packages/" globs: "apps/web/,packages/" alwaysApply: false
Web libraries
Reach for these before writing a helper or adding a dependency. packages/sdk
throws MacroApiError instead of returning Result, and the Bun/Worker services
under services/ throw and validate with zod; elsewhere in apps/web and
packages/ these rules apply.
- FE-35 Branch on unions and literal sets with ts-pattern:
match(x).with(...).exhaustive()..otherwiseonly for open domains (arbitrary strings, error codes, and any payload from a Tauri plugin, worker, or the network: the sender ships separately and.exhaustive()throws on a shape it doesn't know). When such a payload is typed by a closed union you still want checked (a generated service enum, a message union, persisted data), use.exhaustive((unknown) => fallback)instead: it keeps the compile-time check and returns the fallback rather than throwing. Read paths fall back to an empty or unknown value; write paths and request handlers fail the operation (err, a rejected mutation, anok: falsereply) instead of sending or reporting a default. Bare.exhaustive()is for closed, client-built values; parse anything else into one first (stringToItemType,parseEntityType). Enforced in wire adapters, service clients, transports, workers, and SDK event hydrators by ast-grepts-exhaustive-boundary-fallback+tsx-exhaustive-boundary-fallback, CI error. Never hand-writeswitchon a discriminant; aswitchoverevent.keyin a keyboard handler is fine. - FE-36 Fallible operations return neverthrow
Result/ResultAsync. New feature code types errors as{ kind:... }unions matched with ts-pattern; transport code keepsResultError<Code>[]. Guard withif (r.isErr()) return..., then use.value; chain withandThen/mapErr. Enter from throwing code withResultAsync.fromPromise/fromThrowable(orcatchToResultfor legacyResultError). Never wrap aResult-returning call in try/catch;_unsafeUnwrapis test-only. - FE-37 Cross into TanStack Query with
throwOnErr(@core/util/result) inqueryFnandmutationFn. Neverthrowa raw error ornew Error(...)from anisErr()branch:ThrownResultErrorcarries the codes the client's retry and auth policy read. - FE-38 Server state is TanStack Query:
queryOptionsfactories at module scope, called asuseQuery(() => xQueryOptions(id())); keys come from the module'skeys.tsbuilt withcreateQueryKeys, never inline arrays; optimistic mutations useonMutate(cancel, snapshot, patch, return context). GraphQL reads go throughsrc/lib/urql-solid/createLiveQuery. - FE-39 Check
@solid-primitives/*before writing a reactive utility, and declare the package you import inpackage.json. Debounce and throttle through@core/util/debounce(debouncedDependentfor a debounced signal); no hand-rolledclearTimeout/setTimeoutpairs, no lodash. - FE-40 Use the
@ui/components/*wrapper when one exists (Dialog, Tooltip, Select, Tabs, HoverCard,...) instead of importing@kobalte/coredirectly. Merge classes withcn(@ui/utils/classname), nevertwMergeorclsx. - FE-41 HTTP goes through the service clients (
safeFetch,fetchWithToken,fetchWithAuth); rawfetchonly for presigned or blob URLs. - FE-42 zod (v4) validates at boundaries only: route and search params, persisted state, service responses, worker request bodies.
- FE-43 Ids:
uuidv7for server-persisted entities (v5for deterministic ones),crypto.randomUUID()for ephemeral or optimistic ids,nanoidonly for Lexical and canvas node keys. NeverMath.random()ids,uuidv4, orshort-uuid. - FE-44 Dates:
date-fns(and@date-fns/tz) for arithmetic and the house@core/util/date/@core/util/timehelpers;Intl.DateTimeFormatfor locale display. No dayjs, luxon, moment, or Temporal. - FE-45 Default virtualized lists to
virtua; use@tanstack/solid-virtualfor the redesigned Chat sidebar's nested, scroll-aware lists. Persisted UI state usesmakePersistedState(src/lib/persistence) with a zod schema, not rawlocalStoragecalls. - FE-46 Reuse the house helpers instead of re-implementing them:
deepEqual(@core/util/compareUtils),structuredClonefor copies, and@tanstack/pacer(AsyncBatcher,Queuer) for request coalescing.effectstays insidelib/graphql-cache/worker/**andlib/queries/soup/backfill.tsand is never mixed with neverthrow in one module. Don't add lodash, immer, axios, ky, or another validator.