> ## Documentation Index
> Fetch the complete documentation index at: https://docs.refactkit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# RefactKit Environment Variables Complete Reference

> Reference for all RefactKit env vars — where to find each value, which are required, and how to set them for local development and production.

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**.

```bash theme={null}
# 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. |

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

Generate a secret:

```bash theme={null}
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:

```bash theme={null}
SMTP_HOST="smtp.resend.com"
SMTP_PORT=465
SMTP_USER="resend"
SMTP_PASSWORD="re_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
EMAIL_FROM="RefactKit <noreply@yourdomain.com>"
```

<Note>
  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.
</Note>

### 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**. |

<Warning>
  `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.
</Warning>

### 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:

```bash theme={null}
cp .env.example .env.local
```

The full contents of `.env.example`:

```bash theme={null}
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...
```

<Note>
  `.env.local` is gitignored by default. Never commit real credentials to version control.
</Note>