Credentials (Email + Password)

BetterStarter supports email/password authentication through Better Auth emailAndPassword.

Local Development Expectations

Credentials auth works locally without Plunk.

• Sign up and sign in with email/password work with just the database
• Without Plunk, BetterStarter logs reset-password links to the server console in development
• With Plunk configured locally, BetterStarter sends real reset emails
• In production, you need Plunk or another real email provider for reset and other email flows

1. Enable In Config

In src/appConfig.ts set:

credentials: { enabled: true },

2. Fastest Local Test

1. Run pnpm dev
2. Navigate to /auth/sign-up and create an account with email/password
3. Sign out, then sign in at /auth/sign-in
4. Test reset flow from /auth/forgot-password
5. Copy the reset link from the server console

3. Optional: Set Up Plunk For Reset Emails

Credentials auth itself does not require an email provider, but password reset emails do.

1. Create a free account at useplunk.com
2. Verify your sending domain
3. Copy your Secret API key

4. Set Environment Variables

# .env.local
PLUNK_SECRET_API_KEY=your_plunk_secret_api_key
TRANSACTIONAL_EMAIL=noreply@yourdomain.com

5. Test With Real Email Delivery

1. Run pnpm dev
2. Navigate to /auth/sign-up and create an account with email/password
3. Sign out, then sign in at /auth/sign-in
4. Test reset flow from /auth/forgot-password
5. In development, reset links are still logged to the server console

Configuration

Credentials auth is configured in src/features/auth/index.ts:

• emailAndPassword.enabled uses providers.credentials.enabled
• sendResetPassword calls sendResetPasswordEmail
• Reset email template is in src/features/email/templates/ResetPasswordEmail.tsx

In development, the auth layer also logs the generated reset-password URL before sending.

Reset and forgot-password route keys are defined in src/features/auth/constants.ts.

Swapping Email Providers

To switch providers, replace transport logic in src/features/email/transport.ts.

Troubleshooting

• No credentials fields in auth UI — check credentials.enabled in src/appConfig.ts
• No reset email in local development — check the server console for the logged reset link
• Reset email not delivered with Plunk enabled — verify Plunk API key, sender email, and DNS setup (SPF/DKIM/DMARC)
• Reset link invalid or wrong domain — verify APP_BASE_URL and BETTER_AUTH_URL