Configuration

TurboStarter supports multiple different authentication methods:

• Password - the traditional email/password method
• Magic Link - passwordless email link authentication
• OTP - one-time passwords sent to email or phone number
• Passkey - passkeys as an alternative to passwords
• Anonymous - guest mode for unauthenticated users
• OAuth - OAuth providers; Apple, Google, and GitHub are set up by default
• Google One Tap - native, one-click prompt for Google authentication

All authentication methods are enabled by default, but you can easily customize them to your needs. You can enable or disable any method, or configure it separately according to your requirements.

Authentication configuration can be customized through a simple configuration file. The following sections explain the available options and how to configure each authentication method based on your requirements.

API

The server-side authentication configuration lives in packages/auth/src/server.ts. It configures the Better Auth package with the desired providers and settings:

export const auth = betterAuth({
  emailAndPassword: {
    enabled: true,
    requireEmailVerification: true,
    sendResetPassword: () => {},
  },
  emailVerification: {
    sendOnSignUp: true,
    autoSignInAfterVerification: true,
    sendVerificationEmail: () => {},
  },
  database: drizzleAdapter(db, {
    provider: "pg",
    schema,
  }),
  plugins: [
    magicLink({
      sendMagicLink: () => {},
    }),
    passkey(),
    anonymous(),
    expo(),
    nextCookies(),
  ],
  socialProviders: {
    [SocialProvider.APPLE]: {
      clientId: env.APPLE_CLIENT_ID,
      clientSecret: env.APPLE_CLIENT_SECRET,
      appBundleIdentifier: env.APPLE_APP_BUNDLE_IDENTIFIER,
    },
    [SocialProvider.GOOGLE]: {
      clientId: env.GOOGLE_CLIENT_ID,
      clientSecret: env.GOOGLE_CLIENT_SECRET,
    },
    [SocialProvider.GITHUB]: {
      clientId: env.GITHUB_CLIENT_ID,
      clientSecret: env.GITHUB_CLIENT_SECRET,
    },
  },

  /* other configuration options */
});

The configuration is validated against Better Auth's schema at runtime, providing immediate feedback if any settings are incorrect or insecure. This validation ensures your authentication setup remains robust and properly configured.

All authentication routes and handlers are centralized within the Hono API, giving you a single source of truth and complete control over the authentication flow. This centralization makes it easier to maintain, debug, and customize the authentication process as needed.

Read more about it in the official documentation.

UI

We have separate configuration that determines what is displayed to your users in the UI. It's set at apps/web/config/auth.ts.

import { authConfigSchema, type AuthConfig } from "@workspace/auth";

export const authConfig = authConfigSchema.parse({
  providers: {
    password: true,
    magicLink: true,
    emailOtp: false,
    passkey: false,
    anonymous: true,
    oAuth: ["apple", "google"],
  },
}) satisfies AuthConfig;

The configuration is also validated using the Zod schema, so if something is off, you'll see the errors.

NEXT_PUBLIC_AUTH_PASSWORD=false
NEXT_PUBLIC_AUTH_MAGIC_LINK=true

To display third-party providers in the UI, you need to set the oAuth array to include the provider you want to display. The default is Apple, Google and Github:

providers: {
    ...
    oAuth: ["apple", "google", "github"],
    ...
},

Third-party providers

To enable third-party authentication providers, you'll need to:

1. Create an OAuth application in the provider’s developer console (Apple, Google Cloud Console, GitHub, or another supported provider).
2. Set the matching environment variables in your TurboStarter app.

Each provider needs its own credentials and env vars. See the Better Auth OAuth docs for step-by-step setup per provider.