Augur

Migration

Move a site's local UI, types, utilities, hooks, server code and auth onto the augur packages, step by step.

Migration

Replace a site's local code with the augur packages, one area at a time. The runbook covers the configuration around it (dependencies, tsconfig, ESLint, next.config, vitest) and the order to do it in.

1. Install

As in Getting started.

2. UI components

- import { Button } from "@/components/ui/button";
+ import { Button } from "@simpleapps-com/augur-web/button";

- import { Card, CardContent, CardHeader } from "@/components/ui/card";
+ import { Card, CardContent, CardHeader } from "@simpleapps-com/augur-web/card";

Every component has its own entry point (augur-web).

3. Types

- import type { TProductItem } from "@/types/TProductItem";
- import type { TCartLine } from "@/types/TCartLine";
+ import type { TCartLine, TProductItem } from "@simpleapps-com/augur-utils";

4. Utilities

- import { cn } from "@/lib/utils";
+ import { cn } from "@simpleapps-com/augur-utils";

- import { formatPrice } from "@/lib/format-price";
+ import { formatPrice } from "@simpleapps-com/augur-utils";

- import { CACHE_CONFIG } from "@/config/cache.config";
+ import { CACHE_CONFIG } from "@simpleapps-com/augur-utils";

5. Hooks and stores

- import { useCartHdrUid, useCartLines } from "@/store/CartStore";
+ import { useCartHdrUid, useCartLines } from "@simpleapps-com/augur-hooks";

- import { useIsMobile } from "@/hooks/useMobileDetection";
+ import { useIsMobile } from "@simpleapps-com/augur-hooks/web";

- import { useDebounce } from "@/hooks/useDebounce";
+ import { useDebounce } from "@simpleapps-com/augur-hooks";

Local data hooks (useItemPrice, useInvMastDoc, …) have no named replacement: they become proxy queries, as in step 9.

6. Server utilities

- import { getServerQueryClient } from "@/helpers/v2/queryClient";
+ import { getServerQueryClient } from "@simpleapps-com/augur-server";

- import { isDev, isStaging } from "@/lib/environment";
+ import { isDev, isStaging } from "@simpleapps-com/augur-server";

Local SDK caching (cachedSdkCall and the like) goes away: createServerSite() and the proxy cache reads in Redis (augur-server).

7. Auth

  // auth.ts
  import NextAuth from "next-auth";
- import Credentials from "next-auth/providers/credentials";
- // ... the site's own config ...
+ import { site } from "@/lib/augur-site";
+
+ export const { handlers, signIn, signOut, auth } = NextAuth(site.auth!);

For custom callbacks, use createAuthConfig() from @simpleapps-com/augur-server/auth.

8. Theme, providers and tooling

9. Data fetching

Move data fetching to createServerQueryProxy(): it replaces local hook wrappers entirely. The runbook's proxy migration replaces them one at a time. Filter and search params come from augur-utils' serializeCategoryFilters, serializeSearchParams and paginateOffset instead of local transforms.

10. Delete what the packages replaced

Once the site works, delete the local copies: components/ui/, local types, hooks and Zustand stores that now come from augur-hooks, cache config, server caching and environment helpers.

Check after each step

  1. pnpm dev starts without errors.
  2. Every page renders.
  3. Cart add, update and remove work.
  4. Search and filters work.
  5. Sign-in works.
  6. Prefetched pages hydrate without refetching.

What stays in the site

  • Server actions with site-specific business rules.
  • getUserProfile and cartHdrLookup overrides, passed to createAuthConfig.
  • Joomla content hooks, GA4 and other site integrations.
  • Site settings (customer IDs, image CDN, keys) in environment variables.
  • Cart callbacks for useCartActions, which call the site's server actions.