#better auth local install

13 messages · Page 1 of 1 (latest)

lyric onyx
#

When should I use better auth with a local install vs. the normal installation way?

zinc jungleBOT
#

Hi @lyric onyx. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

Use Better Auth’s local install when you need more control over the auth schema or want to use plugins that require schema changes. Otherwise, the normal installation is simpler and usually enough.

Here’s how to choose:

Use the normal installation when

  • You’re happy with the default Better Auth schema that ships with the Convex component.
  • You only need the supported plugins (Anonymous, Email OTP, Generic OAuth, JWT, Magic Link, One Tap, Passkey, Phone Number, 2FA, Username). [Supported plugins]
  • You don’t need to touch Better Auth tables directly from Convex.
  • You want the quickest setup and fewer moving parts. [Basic usage]

In this mode, the schema is bundled in the component and cannot be altered. [Basic usage]

Use Local Install when

Local Install moves the Better Auth component into convex/betterAuth and generates its schema into your repo. [Local install]

Choose this when you need:

  1. Schema customization
    • You want to use Better Auth’s additionalFields or other database options to extend core models (e.g. add fields to user). [UserId in component table]
    • You want to regenerate the schema whenever options change, using the Better Auth CLI. [Local install usage]
#

  1. Plugins beyond the supported list

    • Any Better Auth plugin can be used, but only the “supported plugins” work out of the box.
    • For plugins that require schema changes and aren’t supported, you must use Local Install. [Supported plugins; Discord org plugin thread]

  2. Direct access to Better Auth tables from Convex

  3. Custom indexes for performance

    • You see Better Auth logs suggesting indexes; Local Install lets you generate the schema to a secondary file and add custom indexes without them being overwritten. [Local install usage]

  4. Owning your auth / advanced migrations

    • You want the Better Auth schema checked into your repo and fully under your control (“own your auth”). [Local install]
    • You’re doing migrations that depend on schema customization (e.g. keeping user.userId via additionalFields). [Migrate userId in component table]

If your needs are basic and match the default schema + supported plugins, stick with the normal install. As soon as you need schema-level customization or unsupported plugins, switch to Local Install.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@lyric onyx Kapa.ai is still learning and improving, please let me know how I did by reacting below.

lyric onyx
#

So if I want to customize the users table (not using better auth additional fields) or will want to run migrations down the line, should I do a local install?

#

@zinc jungle

zinc jungleBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

Sorry @lyric onyx, I seem to be having a bit of trouble. Don't worry though, I've pinged my support and they will try to fix me up! :technologist:

Perhaps try again in 15mins?

lyric onyx
#

So if I want to customize the users table (not using better auth additional fields) or will want to run migrations down the line, should I do a local install?
@zinc jungle

zinc jungleBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

Short answer: yes, if you care about customizing Better Auth’s own tables or doing schema-driven migrations, you should plan on Local Install.

Here’s what the docs actually support:

  • With the normal install, the Better Auth schema is fixed inside the component:

    • “For projects not using local install, the default schema provided with the Better Auth component … is used, and cannot be altered.” [Basic usage]
    • You also can’t run the Better Auth CLI to regenerate/update that schema; the CLI-based schema/migration flow is explicitly “only for Local Install.” [Basic usage; Local install]

  • With Local Install:

    • You generate the Better Auth schema into convex/betterAuth/schema.ts using the CLI, and can regenerate it whenever options change. [Local install; Local install usage]
    • You can then:
      • Add custom indexes and keep them across regenerations. [Local install usage]
      • Use Better Auth’s schema-related options (like additionalFields) and regenerate the schema to match. [Local install]
      • Access Better Auth tables directly from Convex functions for more advanced data work and migrations. [Local install; Local install usage]
#

The docs don’t explicitly describe “migrations” beyond schema regeneration and index changes for Local Install, but since the normal install’s schema is locked, any future schema-level changes or data migrations that depend on changing Better Auth tables will be much easier (and in many cases only possible) with Local Install.

So:

  • If by “customize the users table” you mean changing Better Auth’s own user table schema or indexes, you should use Local Install.
  • If you only keep your own separate users table in your app schema and never touch Better Auth tables, normal install is fine; you can still use Convex’s own migrations component for your app tables. [Migrations component]

Given you “will want to run migrations down the line” and care about the auth-side schema, Local Install is the safer choice.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: