Provider configuration

Validate at the boundary

Read environment variables in a server-only module. Validate the selected provider and required values before constructing a client. A missing credential should produce a useful configuration error, not silently select a different provider.

type EmailConfig = {
  provider: 'resend';
  apiKey: string;
  from: string;
};

export function readEmailConfig(
  env: Record<string, string | undefined>,
): EmailConfig {
  const apiKey = env.RESEND_API_KEY;
  const from = env.EMAIL_FROM;
  if (!apiKey || !from) {
    throw new Error('Email requires RESEND_API_KEY and EMAIL_FROM');
  }
  return { provider: 'resend', apiKey, from };
}

Keep secrets server-side

In Next.js, variables without the NEXT_PUBLIC_ prefix remain available to the server environment; public-prefixed values are inlined into browser bundles. Follow the official environment variable guide, and keep privileged clients out of client components.

For example, Supabase client initialization and row-level security should be considered together when configuring a browser client.

Separate environments

Keep a committed .env.example with variable names and placeholder values. Store real values in your local environment or deployment secret store, and avoid copying production credentials into preview environments.

Make operations observable

Record the operation name, provider, duration, result category, and request identifier when available. Make payload logging opt-in and redacted. A configuration error, a rejected request, and an exhausted retry budget should be distinguishable in your telemetry.

• Keep credentials out of logs, errors, URLs, and screenshots.
• Assign timeouts and retry policy in one intentional layer.
• Document who owns credential rotation and provider account access.