Migrating to 2.0

All @xenterprises/nuxt-x-* layers currently ride the hardening line — the published 0.x npm series (nuxt-x-marketing is on 1.x). During this phase breaking changes are allowed, but they are batched into minor releases (never patches) and each one is recorded here. Once every layer is green against the stable-release spec, the program owner cuts a coordinated 2.0.0 across all layers at once — strict semver applies from 2.0 onward.

Versions were realigned to the npm published line on 2026-07-27 — the repo 1.x series was never published, so version numbers continue from npm's last published minors. The coordinated 2.0 cut still happens later by owner decision.

This page collects every breaking note to date. Each entry has a one-line migration pointer; the linked layer section has the full details.

nuxt-x-app

Section: nuxt-x-app

• useXCrud v2 factory API — CRUD calls go through the factory: useXCrud<User>('users').all() for lists, .read(id) for detail, .create() for forms. The legacy crud.fetch(params) is gone — assign crud.filters.value and/or call crud.refresh() instead. v2 also adds cache, staleTime, optimistic, retry, retryDelay, updateMethod, searchDebounce, errorMessages options, invalidateCache() on .all(), and static useXCrud.clearCache(). See useXCrud.
• useXCrud v3 (v0.6.0) — additive, NOT breaking. v3 adds opt-in options on top of the unchanged v2 chainable factory: server-side pagination (page/perPage/setPage()), cache scope (string or Ref) with static useXCrud.clearScope(), sortStyle: 'params' | 'dash', optimistic create() (temp-id insert → replace/rollback), 422 fieldErrors extraction, request cancellation (last-issued-wins), and auth-token injection via $getAuthToken (per-call headers win). Existing v2 call sites (useXCrud(ep).all()/.read(id)/.create()) work unchanged — no migration needed. See useXCrud.
• XACrudTable removed (v0.4) — use XATable + useXCrud instead. See XATable.
• useXQueryInvalidation removed — use Nuxt's clearNuxtData() / refreshNuxtData().
• useAppLayout removed — use useXNavigation.

nuxt-x-app-admin

Section: nuxt-x-app-admin

• Requires @xenterprises/nuxt-x-app@^0.6.0 (was ^0.5.1) — upgrade the base layer first.
• useXCrud v2 factory migration (v0.3.0) — crud objects returned by useXAdmin* composables are now v2 list instances (useXCrud(endpoint).all()); replace crud.fetch(params) with crud.filters.value + crud.refresh(), and use useXCrud(endpoint).read(id) for detail mode. Any consumer touching crud return shapes directly must update.
• Layer is now SPA (v0.3.0) — the layer sets ssr: false, so consumers inherit client-only rendering. Override with ssr: true in your nuxt.config.ts to opt back into SSR.
• x.app.apiUrl now defaults to /api (v0.3.0, was unset) — useXCrud list fetches move from /admin/* to /api/admin/*, matching the documented backend contract. Consumers who pointed a backend at the old /admin/* paths must set NUXT_PUBLIC_X_APP_API_URL (e.g. to the empty path) or move their routes. Direct $fetch calls in composables/components also honor x.app.apiUrl (v0.3.0); the default /api is unchanged, so consumers who never set the var are unaffected.

nuxt-x-app-formkit

Section: nuxt-x-app-formkit

• XFormModal / XFormSlide slot-hijack fix (v0.2.1) — unplugin-formkit previously injected its provider inside the overlay and hijacked the internal #content slot, so the modal/slideover rendered an empty shell. If your overlays render empty, update to >=0.2.1 — no markup change required.

nuxt-x-marketing

Section: nuxt-x-marketing

• Blog moved from Builder.io to Nuxt Content — consumers that relied on NUXT_PUBLIC_BUILDERIO_KEY + Builder models must migrate posts to content/blog/*.md and install the Content peers (@nuxt/content, better-sqlite3).
• Consumers must define their own content.config.ts blog collection — Nuxt Content v3 resolves a collection's source against the layer that defines it, so the layer's default blog collection can never see your posts. Re-declare the collection in your own content.config.ts to bind it to your content dir.

nuxt-x-auth-better

Section: nuxt-x-auth-better

• xAuth.tokens app-config block and useCookieStorage util removed (v0.5.0) — Better Auth manages its own cookies. Drop any consumer code referencing xAuth.tokens or importing the old cookieStorage util.

nuxt-x-affiliate

Section: nuxt-x-affiliate

• Component folder consolidation X/AF/ → XAF/ (next minor) — auto-import names (XAFBanner, XAFDashboard, …) are unchanged; only consumers deep-importing component file paths need to update their import paths.

nuxt-x-restaurants

Section: nuxt-x-restaurants

• No intentional public-API breaks upgrading from 0.9.x — re-run typecheck after upgrading, and prefer peers @xenterprises/nuxt-x-marketing@^1.1.1 and @xenterprises/nuxt-x-cards@^0.2.2 (or higher).

Upgrade checklist

1. Pin all @xenterprises/* layers to the latest published minor and read the entries above for each layer you extend.
2. Re-run typecheck, lint, and your test suite after upgrading.
3. When the coordinated 2.0.0 is announced, upgrade all layers together — mixed 1.x/2.x combinations are not supported.