RefactKit Environment Variables Complete Reference

RefactKit reads configuration from environment variables at startup. For local development, create a .env.local file by copying .env.example. For production, set these variables in your hosting provider’s environment settings (for example, Vercel’s Settings → Environment Variables).

Variables by service

Database

These variables connect RefactKit to your Supabase PostgreSQL database via Drizzle ORM.

Variable	Required	Description
`DATABASE_URL`	Yes	PostgreSQL connection string. Use the Transaction pooler URI from Supabase (port `6543`) — required for serverless and Vercel deployments.

Find DATABASE_URL in your Supabase project under Project Settings → Database → Connection string → URI → Transaction pooler.

# Port 6543 is the transaction pooler — required for serverless
DATABASE_URL="postgresql://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres"

Authentication

Better Auth uses these variables to sign sessions, locate your app, and secure the built-in admin dashboard.

Variable	Required	Description
`BETTER_AUTH_SECRET`	Yes	Secret used to sign and encrypt sessions. Generate with `openssl rand -base64 32`.
`BETTER_AUTH_URL`	Yes	Public base URL of your app. Set to `http://localhost:3000` in development, `https://yourdomain.com` in production.
`BETTER_AUTH_API_KEY`	No	Grants access to the Better Auth admin dashboard at `/api/auth/dashboard`. Only needed if you use the `dash()` plugin.

Rotating BETTER_AUTH_SECRET in production invalidates all existing user sessions immediately. Plan any secret rotation carefully and communicate to users if needed.

Generate a secret:

openssl rand -base64 32

Email

RefactKit sends transactional email (verification, password reset, invitations) over SMTP. The recommended provider is Resend.

Variable	Required	Description
`SMTP_HOST`	Yes	SMTP server hostname. For Resend: `smtp.resend.com`.
`SMTP_PORT`	Yes	SMTP port. For Resend: `465` (TLS).
`SMTP_USER`	Yes	SMTP username. For Resend: `resend`.
`SMTP_PASSWORD`	Yes	SMTP password. For Resend: your API key from Resend → API Keys.
`EMAIL_FROM`	Yes	Sender address shown in emails. Format: `App Name <noreply@yourdomain.com>`. Must be a verified domain in production.

For Resend, your email settings will look like:

SMTP_HOST="smtp.resend.com"
SMTP_PORT=465
SMTP_USER="resend"
SMTP_PASSWORD="re_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
EMAIL_FROM="RefactKit <noreply@yourdomain.com>"

In development, Resend’s sandbox lets you send without a verified domain. For production, add DNS records (SPF, DKIM) to your domain via Resend → Domains to prevent emails landing in spam.

Storage

These variables connect RefactKit to Supabase Storage for file uploads (avatars, organization logos, gallery images).

Variable	Required	Description
`VITE_SUPABASE_URL`	Yes	Your Supabase project URL. Found under Project Settings → API → Project URL.
`SUPABASE_SERVICE_ROLE_KEY`	Yes	Service role key for server-side storage operations. Found under Project Settings → API → service_role.

SUPABASE_SERVICE_ROLE_KEY bypasses Supabase Row Level Security and grants full database access. Never expose it client-side. Never prefix it with VITE_. It must only be used in server functions.

Application

Variable	Required	Description
`VITE_APP_URL`	No	Override the base URL for the auth client. Defaults to a relative URL if omitted. Useful when your app URL differs from `BETTER_AUTH_URL`.

Full reference table

Variable	Required	Where to find it
`DATABASE_URL`	Yes	Supabase → Project Settings → Database → Transaction pooler URI (port 6543)
`BETTER_AUTH_SECRET`	Yes	Generate with `openssl rand -base64 32`
`BETTER_AUTH_URL`	Yes	`http://localhost:3000` in dev, `https://yourdomain.com` in production
`SMTP_HOST`	Yes	Your SMTP provider hostname (`smtp.resend.com` for Resend)
`SMTP_PORT`	Yes	SMTP port (`465` for Resend)
`SMTP_USER`	Yes	SMTP username (`resend` for Resend)
`SMTP_PASSWORD`	Yes	SMTP password / API key (Resend → API Keys)
`EMAIL_FROM`	Yes	Verified sender address (`App Name <noreply@yourdomain.com>`)
`VITE_SUPABASE_URL`	Yes	Supabase → Project Settings → API → Project URL
`SUPABASE_SERVICE_ROLE_KEY`	Yes	Supabase → Project Settings → API → `service_role` key
`BETTER_AUTH_API_KEY`	No	Better Auth dashboard → API Keys (only for admin panel)
`VITE_APP_URL`	No	Override base URL for the auth client (defaults to relative)

The .env.example file

The repository ships with a .env.example file showing every variable with placeholder values. Copy it to .env.local before running the app:

cp .env.example .env.local

The full contents of .env.example:

BETTER_AUTH_SECRET="your_random_32_character_secret_string"
BETTER_AUTH_URL="http://localhost:3000"

VITE_SUPABASE_URL="https://your-project-id.supabase.co"
SUPABASE_SERVICE_ROLE_KEY="eyJhbGci...your_long_service_role_key..._here"

VITE_APP_URL="http://localhost:3000"
DATABASE_URL="postgresql://postgres.your-project-id:your_db_password@aws-0-region.pooler.supabase.com:6543/postgres"

SMTP_HOST="smtp.resend.com"
SMTP_PORT=465
SMTP_USER="resend"
SMTP_PASSWORD="re_your_resend_api_key_here"
EMAIL_FROM="Your App Name <noreply@yourdomain.com>"
BETTER_AUTH_API_KEY=ba...

.env.local is gitignored by default. Never commit real credentials to version control.

Get Started

Core Concepts

Guides

Configuration

Reference

RefactKit Environment Variables Complete Reference

Variables by service

Database

Authentication

Email

Storage

Application

Full reference table

The .env.example file

​Variables by service

​Database

​Authentication

​Email

​Storage

​Application

​Full reference table

​The .env.example file

Variables by service

Database

Authentication

Email

Storage

Application

Full reference table

The .env.example file