Providers
Switch the auth, billing, and email providers without changing application code.
Each pluggable subsystem has multiple providers behind one shared interface.
You select the active provider in packages/config/src/providers.ts and supply
that provider's credentials via environment variables. No application code
changes.
Auth
| Provider | Notes |
|---|---|
better-auth (default) | Full ownership of user data in your Postgres DB |
clerk | Hosted auth via Clerk |
kinde | Hosted auth via Kinde |
neon-auth | Neon-native auth |
To switch: change the value, then set the new provider's keys (e.g. Clerk's publishable/secret keys).
Billing
| Provider | Status |
|---|---|
lemonsqueezy (default) | Fully implemented |
polar / dodo / clerk-billing / kinde-billing | Adapters behind the same interface |
All providers use hosted checkout — the portal never touches raw card data.
Every provider's webhook arrives at the single endpoint POST /webhooks/billing,
where the signature is verified before processing.
Set the provider
Change billingProvider to your choice.
Add credentials
Set the provider's API key, store id, and webhook secret in the environment.
Register the webhook
Point the provider's webhook at {API_URL}/webhooks/billing.
Map plans
Plan → provider variant ids are stored per-plan in the database, seeded from your pricing config.
Email (automatic fallback chain)
Email is special: instead of one provider, you configure an ordered chain.
The email layer tries providers[0] first; if it errors, hits a free-tier
limit, or is down, it automatically shifts to the next configured provider.
Only providers with credentials participate. With none configured, emails are logged to the console — handy for local development.
| Provider | Required env |
|---|---|
resend | RESEND_API_KEY |
nodemailer | SMTP_HOST (+ port/user/pass) |
plunk | PLUNK_API_KEY |
maileroo | MAILEROO_API_KEY |
mailgun | MAILGUN_API_KEY + MAILGUN_DOMAIN |
Retry/backoff per provider is controlled by EMAIL_RETRY_ATTEMPTS and
EMAIL_RETRY_BASE_MS.
Why this design
- One switch, zero refactors — adapters share a stable interface.
- No vendor lock-in — move providers by changing config + env.
- Resilience — the email chain survives a single provider outage automatically.