Environment and Services

Last updated

Source file

docs/foundations/environment-and-services.md

This page explains the generated environment keys, config ownership, and service expectations for the public BrightWeb scaffold. Use it after installation when you need to review the generated platform config and fill in .env.local.

The current public scaffold only generates .env.local for the platform template. The thin site shell has no required environment keys or default feature page.

Exact .env.local flow

  1. Scaffold a platform app with create-bw-app.
  2. Open the generated config/brand.ts and config/modules.ts files in the new project root.
  3. Confirm the generated starter identity and enabled modules match the app you want to validate.
  4. Open the generated .env.local file in the project root.
  5. Replace placeholder service values with the real values for your own environment.

Brand defaults and module selection are starter config, not environment state. Keep them in config/brand.ts and config/modules.ts.

The generated .env.local already includes blank placeholders for every current platform key. For admin-enabled apps, that includes the full app-owned Resend set, so the first-run task is to fill values, not invent env names.

Reminder: match the app URL to the environment

  • NEXT_PUBLIC_APP_URL must always point to the exact public URL of the environment that is currently running the app.
  • In local development, set it in .env.local to your local URL, for example http://localhost:3000.
  • In a shared dev or staging deployment, set the dev/staging domain in that environment's deployment env vars.
  • In production, set the final production domain in the production env vars.
  • Do not reuse the local URL in dev/staging/prod, and do not point dev/staging to the production domain. Auth callbacks and reset-password links are built from this value.

Service keys generated for platform apps

KeyScopeRequired forPurposeWhere the real value comes from
NEXT_PUBLIC_APP_URLpubliccore-authCanonical base URL used by auth callbacks and platform links.The public URL for the current environment: local URL in .env.local, dev/staging domain in dev env vars, and the final domain in production env vars.
NEXT_PUBLIC_SUPABASE_URLpublicplatformSupabase project URL used by auth plus client-side and server-side module access.The target Supabase project settings.
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEYpublicplatformBrowser-safe Supabase key for auth, RLS-backed reads, and RPC access.The target Supabase project settings.
SUPABASE_SECRET_DEFAULT_KEYservercrm, marketing, projects, adminPrivileged server key for Admin, CRM, Marketing, Organizations, and Projects actions.The target Supabase project settings.
SUPABASE_KEEPALIVE_SECRETserveroptional platform operationBearer secret for /api/cron/keepalive.A project-owned random secret.
RESEND_API_KEYserveradmin, marketingAPI key used by app-owned invitation and Marketing delivery calls.Your Resend account.
RESEND_FROM_TRANSACTIONALserveradminSender identity for app-owned transactional flows.A verified sender/domain in Resend.
EMAIL_BRAND_NAMEserveroptionalBrand name shown in transactional invitation emails. Falls back to the sender display name.Your product or company name.
EMAIL_BRAND_LOGO_URLserveroptionalAbsolute or app-relative PNG logo used in transactional invitation emails.A publicly reachable email-safe logo.
EMAIL_BRAND_COLOR_*serveroptionalSemantic #RRGGBB colors used by invitation emails (CANVAS, SURFACE, HEADER, HEADER_TEXT, HEADER_MUTED_TEXT, ACCENT, TEXT, MUTED_TEXT, BORDER, PANEL, BUTTON, BUTTON_TEXT, and WARNING). Invalid values fall back safely.Map the project's theme tokens to the email palette.
MARKETING_FROM_EMAILservermarketingPrimary verified sender address for Marketing campaigns; generated handler composition falls back to RESEND_FROM_EMAIL.A verified sender/domain in Resend.
MARKETING_FROM_NAMEservermarketingDisplay name for Marketing campaigns.Your product or company name.
RESEND_FROM_MARKETINGserverlegacy infra helperCompatibility value read by getMarketingSender(); new Marketing handlers use MARKETING_FROM_EMAIL.A verified sender/domain in Resend.
CONTACT_TO_EMAILserveradminDestination inbox for app-owned contact notifications.Inbox address owned by the client.
RESEND_WEBHOOK_SECRETservermarketingSvix secret used to verify inbound Resend webhook signatures.The webhook secret configured in Resend.
MARKETING_WORKER_SECRETservermarketingShared bearer secret for the internal Marketing worker endpoint.A project-owned random secret.
MARKETING_TEST_EMAILserveroptional Marketing operationDefault recipient for app-owned Marketing test-send tooling.A test mailbox controlled by the project team.

Current Marketing data boundary

  • Supabase is the source of truth for Marketing topics, contact subscriptions, unsubscribe tokens, suppressions, campaigns, segments, workflows, recipients, and message events.
  • Resend is the injected delivery provider. Provider message and webhook identifiers are recorded against the Supabase-owned delivery rows; Resend Topics are not the BrightWeb consent model.
  • Operational contact identity lives in CRM, while organization membership and invitations live in Organizations. Selecting Marketing resolves both dependencies.
  • Global application notification preferences in Core remain separate from consent to Marketing topics.
  • Provider secrets stay in the generated server-only handler composition. Browser UI receives only the package's HTTP client contract.

Auth email delivery vs app-owned email delivery

  • Auth email flows (signUp, resend confirmation, reset password) are Supabase-owned and use supabase.auth.*.
  • Auth provider and SMTP behavior are configured in Supabase Auth settings, not in the app transport layer.
  • Generate Supabase template files with createAuthEmailTemplates; pass the same semantic palette used by app-owned invitations so every account email stays on-brand.
  • Hosted Supabase projects do not read repository template files. Use @brightweblabs/core-auth/email/supabase-management inside a Next.js server runtime, or its /node subpath in an operational Node script, to back up, synchronize, and verify the 12 generated subjects and HTML bodies through the Management API. The browser runtime guard remains active in both entrypoints.
  • syncSupabaseAuthEmailTemplates requires an onBackup callback and completes it before sending a PATCH. Its PATCH contains only the 24 supported subject/body fields. Afterward it verifies exact template parity and fails post-update verification if SMTP, redirects, providers, invitation content, or any other unmanaged Auth setting changed. The captured rollbackPayload restores the 24 template fields; unexpected drift in an unmanaged setting must be inspected and repaired separately.
  • App-owned transactional, contact, invite, and marketing flows should call Resend via @brightweblabs/infra/server.
TS
import { writeFile } from "node:fs/promises";

import { createAuthEmailTemplates } from "@brightweblabs/core-auth/email";
import { syncSupabaseAuthEmailTemplates } from "@brightweblabs/core-auth/email/supabase-management/node";

const templates = createAuthEmailTemplates(brand);
const result = await syncSupabaseAuthEmailTemplates({
  projectRef: process.env.SUPABASE_PROJECT_REF ?? "",
  accessToken: process.env.SUPABASE_ACCESS_TOKEN ?? "",
  templates,
  onBackup: (backup) => writeFile(
    `.supabase-auth-email-backup-${backup.capturedAt.replaceAll(":", "-")}.json`,
    `${JSON.stringify(backup, null, 2)}\n`,
    { encoding: "utf8", mode: 0o600 },
  ),
});

console.log(result.changed ? "Hosted templates synchronized." : "Hosted templates already match.");

Keep this synchronization separate from supabase config push. Every hosted app has its own Supabase project ref and must run the scoped synchronization for that project after generating its branded templates.

Generated platform config files

config/brand.ts

  • Holds company name, product name, slug, tagline, contact email, support email, and primary brand color.
  • Generated from the scaffold slug plus BrightWeb starter defaults.
  • Edit this file when the starter identity should change.

config/modules.ts

  • Holds module metadata plus the enabled state for CRM, Marketing, Projects, and Admin.
  • Generated from the module choices you made during scaffold time.
  • Edit this file when you want package mounts and shell wiring to reflect a different module set.

What each template expects

Site

  • No generated .env.local
  • No required external services for the thin site shell
  • First customization usually happens in config/site.ts, app/page.tsx, and app/globals.css

Platform

  • Generated .env.local
  • Supabase and Resend are the main external services the starter expects
  • Admin-enabled apps include blank placeholders for the full app-owned Resend/admin key set in .env.local
  • Optional module routes need the matching database schema and access model in the target client database
  • Starter identity and module selection live in config/brand.ts and config/modules.ts

Validate after editing .env.local

For platform apps:

  1. Run the app locally.
  2. Open /.
  3. Run the build, then validate /crm or /admin/users when those package mounts are enabled.
  4. Confirm the starter reports the expected readiness state.
  5. Open the generated playground routes and confirm they either connect successfully or show the exact missing configuration you still need to fill in.

For the route-by-route checks, use Validate Your Starter.

Related docs