Configuration

TurboStarter supports three different authentication methods:

• Password - the traditional email/password method
• Magic Link - passwordless email link authentication
• OAuth - OAuth providers, Google and Github are set up by default

All authentication methods are enabled by default, but you can easily customize them to your needs. You can enable or disable any method, and configure them 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 is set at packages/auth/src/server.ts. It confgures Better Auth package to use the correct providers and settings:

export const auth = betterAuth({
  emailAndPassword: {
    enabled: true,
    requireEmailVerification: true,
    sendResetPassword: () => {},
  },
  emailVerification: {
    sendOnSignUp: true,
    autoSignInAfterVerification: true,
    sendVerificationEmail: () => {},
  },
  database: drizzleAdapter(db, {
    provider: "pg",
    usePlural: true,
    schema,
  }),
  plugins: [
    magicLink({
      sendMagicLink: () => {},
    }),
    expo(),
    nextCookies(),
  ],
  socialProviders: {
    [SOCIAL_PROVIDER.GITHUB]: {
      clientId: env.GITHUB_CLIENT_ID,
      clientSecret: env.GITHUB_CLIENT_SECRET,
    },
    [SOCIAL_PROVIDER.GOOGLE]: {
      clientId: env.GOOGLE_CLIENT_ID,
      clientSecret: env.GOOGLE_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.

The recommendation is to not update this directly - instead, please define the environment variables and override the default behavior.

import { SOCIAL_PROVIDER, authConfigSchema } from "@turbostarter/auth";
 
import { env } from "~/lib/env";
 
import type { AuthConfig } from "@turbostarter/auth";
 
export const authConfig = authConfigSchema.parse({
  providers: {
    password: env.NEXT_PUBLIC_AUTH_PASSWORD,
    magicLink: env.NEXT_PUBLIC_AUTH_MAGIC_LIND,
    oAuth: [SOCIAL_PROVIDER.GOOGLE, SOCIAL_PROVIDER.GITHUB],
  },
}) satisfies AuthConfig;

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

For example, if you want to switch from password to magic link, you'd set the following environment variables:

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 Google and Github:

providers: {
    ...
    oAuth: [SOCIAL_PROVIDER.GOOGLE, SOCIAL_PROVIDER.GITHUB],
    ...
},

Third party providers

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

1. Set up an OAuth application in the provider's developer console (like Google Cloud Console, Github Developer Settings or any other provider you want to use)
2. Configure the corresponding environment variables in your TurboStarter application

Each OAuth provider requires its own set of credentials and environment variables. Please refer to the Better Auth documentation for detailed setup instructions for each supported provider.