Migrating to per-feature components

Move from the all-in-one component to installing only the auth features you use.

The full @vortex-api/convex-auth/convex.config component still works and is the safest starting point for existing consumers. Migration to feature-gated components is optional and driven by which auth features you actually use — see Feature-gated components for the mount table and what each component includes.

Migration steps

1. Keep your current convex/convex.config.ts with the full component until the split setup is verified.

2. Create a new convex/convex.config.ts that imports only the components you need:

   import { defineApp } from "convex/server";
   import { v } from "convex/values";
   import authCore from "@vortex-api/convex-auth/convex.config/core";
   
   const app = defineApp({
     env: {
       JWT_PRIVATE_KEY: v.string(),
       JWKS: v.string(),
     },
   });
   
   app.use(authCore, {
     env: {
       JWT_PRIVATE_KEY: app.env.JWT_PRIVATE_KEY,
       JWKS: app.env.JWKS,
     },
   });
   
   export default app;

3. Update convex/auth.ts to use the split components API:

   import { components } from "./_generated/api";
   import { convexAuth } from "@vortex-api/convex-auth/convex";
   
   export const auth = convexAuth({
     components: { core: components.convexAuthCore },
     // ... emailAndPassword, oauth, etc.
   });

4. Run pnpm dlx convex dev or pnpm dlx convex deploy to regenerate bindings and push the new schema.

5. Run your full local proof (pnpm run typecheck, pnpm run build, pnpm test).

What happens to old tables?

Convex does not drop tables when they are removed from the active schema. Data in tables from the full component (e.g. organizations, api_keys) remains in the database but is no longer referenced by the active component. You can delete unused data through the Convex dashboard or run a migration if you are sure the feature is no longer needed.

Rollback

If you need to return to the full component, restore the original convex.config.ts and auth.ts, then run pnpm dlx convex dev again. The full component will remount and expose the same components.convexAuth handle.