Configuration

StartupKit uses Better Auth for authentication. This guide covers how auth is structured in your monorepo.

Architecture

Auth in StartupKit has two layers:

Package	Purpose
`@startupkit/auth`	NPM package with React hooks and utilities
`@repo/auth`	Your customizable auth configuration

The @repo/auth package in your monorepo imports from both better-auth directly and @startupkit/auth. This gives you full control over your auth configuration while using StartupKit's convenience utilities.

Project Structure

packages/auth/
├── src/
│   ├── lib/
│   │   └── auth.ts        # Better Auth configuration
│   ├── components/
│   │   ├── index.ts
│   │   └── provider.tsx   # AuthProvider wrapper
│   ├── hooks/
│   │   └── use-auth.ts    # Typed useAuth hook
│   ├── index.ts           # Client exports + authClient
│   ├── server.ts          # Server exports (withAuth, handler)
│   └── types.ts           # User/Session types
└── package.json

Server Configuration

1. Configure Better Auth

Create your Better Auth instance in packages/auth/src/lib/auth.ts:

packages/auth/src/lib/auth.ts

import {  } from "better-auth"
import {  } from "better-auth/adapters/drizzle"
import {  } from "better-auth/next-js"
import {  } from "better-auth/plugins"
import * as  from "@repo/db"

export const  = ({
  : "/auth",
  : (., {
    : "pg",
    : {
      : .,
      : .,
      : .,
      : .
    }
  }),
  : [
    ({
      : async ({ ,  }) => {
        // Send OTP via your email service
      }
    }),
    ()
  ],
  : {
    : {
      : .. || "",
      : .. || "",
    }
  }
})

2. Create Server Exports

Export server utilities in packages/auth/src/server.ts:

packages/auth/src/server.ts

import {  } from "better-auth/next-js"
import {  } from "next/headers"
import {  } from "./lib/auth"

export {  }

export type  = typeof .$Infer.Session.session
export type  = typeof .$Infer.Session.user

export function () {
  return (.handler)
}

export async function () {
  const  = await .api.getSession({
    : await ()
  })

  return {
    : ?.user ?? null,
    : ?.session ?? null
  }
}

3. Create API Route

Add the auth handler route in your Next.js app:

apps/web/app/auth/[...all]/route.ts

import {  } from "@repo/auth/server"

export const { ,  } = ()

Client Configuration

1. Create Auth Client

Set up the Better Auth client in packages/auth/src/index.ts:

packages/auth/src/index.ts

import {  } from "better-auth/client/plugins"
import {  } from "better-auth/react"

export * from "./components"
export * from "./types"

export const  = ({
  : "/auth",
  : [()]
})

2. Create AuthProvider

Wrap the StartupKit AuthProvider in packages/auth/src/components/provider.tsx:

packages/auth/src/components/provider.tsx

"use client"

import {  as  } from "@startupkit/auth"
import type React from "react"
import {  } from "../index"
import type {  } from "../types"

interface AuthProviderProps {
  : React.
  ?: 
}

export function ({ ,  }: AuthProviderProps) {
  return (
    < ={} ={}>
      {}
    </>
  )
}

3. Add to App Layout

Wrap your app with the AuthProvider:

apps/web/app/providers.tsx

"use client"

import {  } from "@repo/auth"
import type {  } from "@repo/auth"

interface ProvidersProps {
  : .
  ?: 
}

export function ({ ,  }: ProvidersProps) {
  return (
    < ={}>
      {}
    </>
  )
}

apps/web/app/layout.tsx

import {  } from "@repo/auth/server"
import {  } from "./providers"

export default async function ({
  
}: {
  : .
}) {
  const {  } = await ()

  return (
    <>
      <>
        < ={}>
          {}
        </>
      </>
    </>
  )
}

Environment Variables

Add these to your .env.local:

# Database
DATABASE_URL="postgresql://..."

# Google OAuth (optional)
GOOGLE_CLIENT_ID="your-client-id"
GOOGLE_CLIENT_SECRET="your-client-secret"

Authentication Providers

The example above configures Email OTP and Google OAuth. Better Auth supports many more providers including GitHub, Apple, Discord, and others.

See the Better Auth Providers documentation for the full list and configuration options.

To add a provider:

Add the provider config to auth.ts
Add the client plugin to authClient if needed
Add environment variables

Next Steps

requireAuth - Protect pages with redirect
withAuth - Get session for conditional rendering
Session Management - Configure session duration

On this page