Integrate with Core Kit

Choose the Core capabilities

Port only the product infrastructure you need. Follow dependencies outward from the selected feature:

Account flows are the usual first slice because organizations, billing, and admin all depend on Core's user and session model.

Merge workspace configuration

Copy packages that do not exist in AI Kit, then merge the overlapping packages file by file. Add the required catalog versions and allowBuilds entries from Core's pnpm-workspace.yaml.

Do not copy either lockfile over the other. Keep AI Kit's root scripts unless a selected Core package requires an additional task, then regenerate the dependency graph:

pnpm install

Resolve shared dependency versions once at the workspace catalog. In particular, align Next.js, Expo, React Native, Tailwind CSS, Turborepo, Better Auth, Drizzle, and the AI SDK before debugging application code.

Adopt Core authentication

Replace AI Kit's minimal packages/auth implementation with Core's package and its dependencies. Core auth already supports the anonymous plugin, so AI templates can keep frictionless sessions while you add email and password, magic links, email OTP, passkeys, OAuth, two-factor authentication, admin, and organizations.

Preserve AI Kit's product behavior deliberately:

• Keep anonymous auth enabled if guests may generate content.
• Decide when an anonymous account must upgrade before storing or sharing data.
• Keep the cookie prefix stable for existing users, or plan a forced sign-in migration.
• Add the AI mobile scheme to trusted origins if you retain it.
• Use Core's auth client in both AI apps instead of maintaining parallel clients.

Merge Core's auth environment definitions and app feature flags into the AI app env configuration. Never infer enabled server plugins only from a client-side flag.

Combine the database schemas

Keep AI Kit's feature schemas:

packages/db/src/schema/chat.ts
packages/db/src/schema/rag.ts
packages/db/src/schema/image.ts

Port Core's auth and selected billing or organization tables. Replace AI Kit's minimal auth.ts only after checking that the resulting Better Auth schema contains every field and table required by the enabled Core plugins.

Both kits define a different customer table. AI Kit uses it for a simple credit balance, while Core billing uses it for payment-provider customers. They cannot coexist under the same table or export name. Rename the AI model to a dedicated ai_credit or ledger table, or remove it and enforce Core plan entitlements instead.

AI Kit's schema object prefixes relations from feature-specific PostgreSQL schemas. Preserve that object and add the Core modules to it rather than converting the index to Core's simple barrel:

import * as auth from "./auth";
import * as billing from "./billing";
import * as chat from "./chat";
import * as image from "./image";
import * as rag from "./rag";

export const schema = {
  ...auth,
  ...billing,
  ...prefix(chat, "chat"),
  ...prefix(rag, "rag"),
  ...prefix(image, "image"),
};

The exact modules depend on the Core features you selected. Add your renamed credit schema only if you keep that model. Keep the existing prefix helper and exports required by @workspace/db/schema/*.

If you keep RAG, the target PostgreSQL instance must support pgvector. Preserve AI Kit's CREATE EXTENSION vector migration and use a compatible local image or hosted database. Other templates do not require pgvector.

Generate a migration from the final TypeScript schema:

pnpm with-env pnpm --filter @workspace/db db:generate
pnpm with-env pnpm --filter @workspace/db db:migrate

For an existing AI database, review user, account, session, and cookie compatibility before deployment. Do not run Core's historical migrations and AI Kit's historical migrations independently against the same database.

Add Core routers to the AI API

Keep AI Kit's aiRouter, storage routes, streaming response handling, AI middleware, and error mapping. Port the selected Core routers into packages/api/src/modules, then register them in AI Kit's existing Hono chain:

const appRouter = new Hono()
  .basePath("/api")
  // existing middleware
  .route("/ai", aiRouter)
  .route("/auth", authRouter)
  .route("/billing", billingRouter)
  .route("/organizations", organizationRouter)
  .route("/admin", adminRouter)
  .route("/storage", storageRouter)
  .onError(onError);

Only register routers you ported. Merge middleware by responsibility:

• Use Core's session and authorization checks for account, organization, admin, and billing routes.
• Keep AI rate limiting and usage deduction around paid model calls.
• Keep validation and localization behavior consistent across all routes.
• Preserve the request abort signal when streaming AI responses.

Reconcile billing and AI usage

AI Kit includes a demonstration credit balance. Core Kit includes subscription and purchase providers. Decide on one server-side policy before exposing AI features to paid users:

1. Plan entitlement: a plan enables a feature, with rate limits enforced separately.
2. Included allowance: a plan grants a recurring AI allowance.
3. Purchased credits: users buy a balance consumed per operation.
4. Hybrid: plans include usage and allow top-ups.

The API must check the policy before invoking a model. Client-side credit displays are informative only.

Keep provider-reported usage and the product's billable units separate. Provider tokens, generated images, audio seconds, and product credits are not interchangeable accounting records.

Port Core application surfaces

Bring Core routes and modules into the AI apps without replacing AI Kit's route groups or root providers.

For web, typical additions are:

apps/web/src/app/[locale]/auth
apps/web/src/app/[locale]/dashboard
apps/web/src/app/[locale]/admin
apps/web/src/modules/auth
apps/web/src/modules/billing
apps/web/src/modules/organization
apps/web/src/modules/user

Merge the root layout providers so there is one auth client, query client, theme, i18n instance, analytics provider, and monitoring provider.

Add each imported Core workspace package to apps/web/next.config.ts, and merge its validated variables into apps/web/env.config.ts, .env.example, and apps/web/turbo.json.

For mobile, port the matching Core setup, auth, dashboard, settings, and billing routes. Keep AI Kit's (apps) screens and move or link them into the authenticated Core navigation according to your product.

If you add Core's browser extension, treat it as a client of the existing web API. The extension AI recipe covers the platform-specific boundary.

Verify identities, access, and cost controls

Run workspace checks, then test the combined behavior rather than each kit in isolation:

pnpm lint
pnpm --filter web build

Verify:

1. Anonymous users retain their own AI history.
2. Account upgrade preserves or intentionally migrates anonymous data.
3. Organization switching cannot expose another tenant's AI records.
4. Billing and usage checks run before every paid provider call.
5. Admin permissions do not imply ownership of user AI data unless your policy says so.
6. Web and mobile resolve the same session and API types.
7. Deleting a user applies the intended cascade or retention policy to chats, files, images, and usage records.