refactor: make kv redis optional (#326)

**@vercel/kv** redis is now optional for the dashboard. The app boots
and runs core auth + dashboard flows without `KV_REST_API_URL` /
`KV_REST_API_TOKEN` configured.

Author: drankou

.env.example

@@ -9,10 +9,6 @@ SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
 # Resolves Infrastructure and Dashboard API + E2B SDK configuration 
 NEXT_PUBLIC_E2B_DOMAIN=e2b.dev
 
-### KV database configuration
-KV_REST_API_TOKEN=
-KV_REST_API_URL=
-
 ### =================================
 ### REQUIRED CLIENT ENVIRONMENT VARIABLES
 ### =================================
@@ -37,6 +33,12 @@ NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
 ### ZeroBounce API key for email validation
 # ZEROBOUNCE_API_KEY=
 
+### Optional KV database configuration
+### Required only for KV-backed capabilities such as alternate-email warning dedupe.
+### Must be Vercel/Upstash Redis REST compatible; raw redis://localhost:6379 is not supported by @vercel/kv.
+# KV_REST_API_TOKEN=
+# KV_REST_API_URL=
+
 ### Plain API key for customer support integration
 # (Required if NEXT_PUBLIC_INCLUDE_REPORT_ISSUE=1)
 # PLAIN_API_KEY=

README.md

@@ -57,21 +57,7 @@ cp .env.example .env.local
 
 4. Set up required services:
 
-#### a. Key-Value Store Setup
-This project requires a Redis-compatible key-value store. You'll need to:
-
-1. Set up a Redis instance (self-hosted or using a cloud provider)
-2. Configure the following environment variables in your `.env.local` file:
-   ```
-   KV_URL=your_redis_connection_string
-   KV_REST_API_URL=your_redis_rest_api_url
-   KV_REST_API_TOKEN=your_redis_api_write_token
-   KV_REST_API_READ_ONLY_TOKEN=your_redis_api_read_token
-   ```
-
-> **Note**: For production deployments, we use Vercel KV Storage integration, which provides a managed Redis-compatible store and automatically configures these environment variables. You can add this integration through the Vercel dashboard when deploying your project.
-
-#### b. Supabase Setup
+#### a. Supabase Setup
 1. Create a new Supabase project
 2. Go to Project Settings > API
 3. Copy the `anon key` & `service_role key` to populate `.env.local`
@@ -97,10 +83,23 @@ This project requires a Redis-compatible key-value store. You'll need to:
    {{ .SiteURL }}/api/auth/confirm?token_hash={{ .TokenHash }}&type=email&next={{ .RedirectTo }}&confirmation_url={{ .ConfirmationURL }}
    ```
 
-#### c. Supabase Storage Setup
+#### b. Supabase Storage Setup
 1. Go to Storage > Buckets
 2. Create a new **public** bucket named `profile-pictures`
 
+#### c. Key-Value Store Setup (Optional)
+Redis/KV is optional for standard dashboard deployments, including local, enterprise, and on-prem environments. The dashboard can boot and run core auth and dashboard workflows without KV configured.
+
+KV is currently used for optional capability checks and for deduplicating ZeroBounce alternate-email warnings. If you need those capabilities, configure a Vercel/Upstash Redis REST-compatible store:
+   ```
+   KV_REST_API_URL=your_redis_rest_api_url
+   KV_REST_API_TOKEN=your_redis_api_write_token
+   ```
+
+> **Note**: `@vercel/kv` expects a Redis REST API. A raw Redis server such as `redis://localhost:6379` is not compatible without an Upstash-compatible REST proxy.
+
+> **Health check**: When `KV_REST_API_URL` and `KV_REST_API_TOKEN` are set, `/api/health` will report `503 degraded` if KV is unreachable. Leave both unset to opt out of the KV health check entirely.
+
 #### d. Start the development server
 ```bash
 # Using Bun (recommended)

scripts/check-app-env.ts

@@ -6,6 +6,13 @@ loadEnvConfig(projectDir)
 
 const schema = serverSchema
   .merge(clientSchema)
+  .refine(
+    (data) => Boolean(data.KV_REST_API_URL) === Boolean(data.KV_REST_API_TOKEN),
+    {
+      message: 'KV_REST_API_URL and KV_REST_API_TOKEN must be set together',
+      path: ['KV_REST_API_URL', 'KV_REST_API_TOKEN'],
+    }
+  )
   .refine(
     (data) => {
       if (data.NEXT_PUBLIC_INCLUDE_BILLING === '1') {

src/app/api/health/route.ts

@@ -1,42 +1,24 @@
 import { NextResponse } from 'next/server'
 import { api } from '@/core/shared/clients/api'
-import { kv } from '@/core/shared/clients/kv'
+import { pingKv } from '@/core/shared/clients/kv'
 import { l, serializeErrorForLog } from '@/core/shared/clients/logger/logger'
 
 export const maxDuration = 10
 
-export async function GET() {
-  const checks = {
-    kv: false,
-    dashboardApi: false,
-  }
-
+async function checkDashboardApi(): Promise<boolean> {
   try {
-    await kv.ping()
-    checks.kv = true
-  } catch (error) {
+    const { error } = await api.GET('/health', {})
+    if (!error) {
+      return true
+    }
+
     l.error(
       {
-        key: 'health_check:kv_error',
-        error: serializeErrorForLog(error),
+        key: 'health_check:dashboard_api_error',
+        error,
       },
-      'KV health check failed'
+      'Dashboard API health check failed'
     )
-  }
-
-  try {
-    const { error } = await api.GET('/health', {})
-    if (!error) {
-      checks.dashboardApi = true
-    } else {
-      l.error(
-        {
-          key: 'health_check:dashboard_api_error',
-          error,
-        },
-        'Dashboard API health check failed'
-      )
-    }
   } catch (error) {
     l.error(
       {
@@ -47,15 +29,59 @@ export async function GET() {
     )
   }
 
-  const allHealthy = checks.kv && checks.dashboardApi
+  return false
+}
+
+export async function GET() {
+  const [kvStatus, dashboardApi] = await Promise.all([
+    pingKv(),
+    checkDashboardApi(),
+  ])
+
+  const checks: { kv?: boolean; dashboardApi: boolean } = { dashboardApi }
+
+  if (kvStatus.configured) {
+    checks.kv = kvStatus.available
+  }
+
+  if (kvStatus.status === 'misconfigured') {
+    // Surface misconfiguration in the response body so it's visible
+    // without scraping logs.
+    checks.kv = false
+    l.error(
+      {
+        key: 'health_check:kv_misconfigured',
+      },
+      'KV health check is misconfigured'
+    )
+  }
+
+  if (kvStatus.status === 'error') {
+    l.error(
+      {
+        key: 'health_check:kv_error',
+        error: serializeErrorForLog(kvStatus.error),
+      },
+      'KV health check failed'
+    )
+  }
+
+  // KV is required *only when configured*. If an operator has wired it up,
+  // they expect it to work — so failure or misconfiguration must degrade
+  // the overall status. When KV is intentionally absent (not_configured),
+  // it contributes nothing to the health check.
+  const kvRequiredAndHealthy =
+    kvStatus.status === 'not_configured' || kvStatus.status === 'ok'
+
+  const allRequiredHealthy = dashboardApi && kvRequiredAndHealthy
 
   return NextResponse.json(
     {
-      status: allHealthy ? 'ok' : 'degraded',
+      status: allRequiredHealthy ? 'ok' : 'degraded',
       checks,
     },
     {
-      status: allHealthy ? 200 : 503,
+      status: allRequiredHealthy ? 200 : 503,
       headers: {
         // vercel infra respects this to cache on cdn
         'Cache-Control': 'public, max-age=30, must-revalidate',

src/core/server/functions/auth/validate-email.ts

@@ -1,5 +1,5 @@
-import { kv } from '@vercel/kv'
 import { KV_KEYS } from '@/configs/keys'
+import { getKvValue, setKvValue } from '@/core/shared/clients/kv'
 import { l, serializeErrorForLog } from '@/core/shared/clients/logger/logger'
 
 /**
@@ -102,16 +102,52 @@ export const shouldWarnAboutAlternateEmail = async (
   validationResult: EmailValidationResponse
 ): Promise<boolean> => {
   if (validationResult.sub_status === 'alternate') {
-    const warnedAlternateEmail = await kv.get(
+    const warnedAlternateEmail = await getKvValue<boolean>(
       KV_KEYS.WARNED_ALTERNATE_EMAIL(validationResult.address)
     )
 
-    if (!warnedAlternateEmail) {
-      await kv.set(
+    if (!warnedAlternateEmail.ok) {
+      l.warn(
+        {
+          key: 'validate_email:alternate_email_kv_unavailable',
+          error:
+            warnedAlternateEmail.reason === 'error'
+              ? serializeErrorForLog(warnedAlternateEmail.error)
+              : undefined,
+          context: {
+            reason: warnedAlternateEmail.reason,
+          },
+        },
+        'Skipping alternate email warning because KV is unavailable'
+      )
+
+      return false
+    }
+
+    if (!warnedAlternateEmail.value) {
+      const setResult = await setKvValue(
         KV_KEYS.WARNED_ALTERNATE_EMAIL(validationResult.address),
         true
       )
 
+      if (!setResult.ok) {
+        l.warn(
+          {
+            key: 'validate_email:alternate_email_kv_set_unavailable',
+            error:
+              setResult.reason === 'error'
+                ? serializeErrorForLog(setResult.error)
+                : undefined,
+            context: {
+              reason: setResult.reason,
+            },
+          },
+          'Skipping alternate email warning because KV could not persist state'
+        )
+
+        return false
+      }
+
       return true
     }
   }

src/core/shared/clients/kv.ts

@@ -1 +1,83 @@
-export { kv } from '@vercel/kv'
+import { kv } from '@vercel/kv'
+
+export type OptionalKvResult<T> =
+  | { ok: true; configured: true; value: T }
+  | {
+      ok: false
+      configured: false
+      reason: 'not_configured' | 'misconfigured'
+    }
+  | { ok: false; configured: true; reason: 'error'; error: unknown }
+
+export type KvCapabilityStatus =
+  | { configured: false; available: false; status: 'not_configured' }
+  | { configured: false; available: false; status: 'misconfigured' }
+  | { configured: true; available: true; status: 'ok' }
+  | { configured: true; available: false; status: 'error'; error: unknown }
+
+function getKvConfigStatus() {
+  const hasUrl = Boolean(process.env.KV_REST_API_URL)
+  const hasToken = Boolean(process.env.KV_REST_API_TOKEN)
+
+  if (!(hasUrl || hasToken)) {
+    return 'not_configured'
+  }
+
+  if (hasUrl && hasToken) {
+    return 'configured'
+  }
+
+  return 'misconfigured'
+}
+
+export function isKvConfigured() {
+  return getKvConfigStatus() === 'configured'
+}
+
+export async function pingKv(): Promise<KvCapabilityStatus> {
+  const configStatus = getKvConfigStatus()
+
+  if (configStatus !== 'configured') {
+    return { configured: false, available: false, status: configStatus }
+  }
+
+  try {
+    await kv.ping()
+    return { configured: true, available: true, status: 'ok' }
+  } catch (error) {
+    return { configured: true, available: false, status: 'error', error }
+  }
+}
+
+export async function getKvValue<T>(
+  key: string
+): Promise<OptionalKvResult<T | null>> {
+  const configStatus = getKvConfigStatus()
+
+  if (configStatus !== 'configured') {
+    return { ok: false, configured: false, reason: configStatus }
+  }
+
+  try {
+    return { ok: true, configured: true, value: await kv.get<T>(key) }
+  } catch (error) {
+    return { ok: false, configured: true, reason: 'error', error }
+  }
+}
+
+export async function setKvValue(
+  key: string,
+  value: unknown
+): Promise<OptionalKvResult<unknown>> {
+  const configStatus = getKvConfigStatus()
+
+  if (configStatus !== 'configured') {
+    return { ok: false, configured: false, reason: configStatus }
+  }
+
+  try {
+    return { ok: true, configured: true, value: await kv.set(key, value) }
+  } catch (error) {
+    return { ok: false, configured: true, reason: 'error', error }
+  }
+}

src/lib/env.ts

@@ -2,8 +2,8 @@ import { z } from 'zod'
 
 export const serverSchema = z.object({
   SUPABASE_SERVICE_ROLE_KEY: z.string().min(1),
-  KV_REST_API_TOKEN: z.string().min(1),
-  KV_REST_API_URL: z.url(),
+  KV_REST_API_TOKEN: z.string().min(1).optional(),
+  KV_REST_API_URL: z.url().optional(),
 
   ENABLE_USER_BOOTSTRAP: z.string().optional(),
   DASHBOARD_API_ADMIN_TOKEN: z.string().min(1).optional(),