Environment and Services
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
- Scaffold a
platformapp withcreate-bw-app. - Open the generated
config/brand.tsandconfig/modules.tsfiles in the new project root. - Confirm the generated starter identity and enabled modules match the app you want to validate.
- Open the generated
.env.localfile in the project root. - 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.tsandconfig/modules.ts.The generated
.env.localalready 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_URLmust always point to the exact public URL of the environment that is currently running the app.- In local development, set it in
.env.localto your local URL, for examplehttp://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
| Key | Scope | Required for | Purpose | Where the real value comes from |
|---|---|---|---|---|
NEXT_PUBLIC_APP_URL | public | core-auth | Canonical 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_URL | public | platform | Supabase project URL used by auth plus client-side and server-side module access. | The target Supabase project settings. |
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY | public | platform | Browser-safe Supabase key for auth, RLS-backed reads, and RPC access. | The target Supabase project settings. |
SUPABASE_SECRET_DEFAULT_KEY | server | crm, marketing, projects, admin | Privileged server key for Admin, CRM, Marketing, Organizations, and Projects actions. | The target Supabase project settings. |
SUPABASE_KEEPALIVE_SECRET | server | optional platform operation | Bearer secret for /api/cron/keepalive. | A project-owned random secret. |
RESEND_API_KEY | server | admin, marketing | API key used by app-owned invitation and Marketing delivery calls. | Your Resend account. |
RESEND_FROM_TRANSACTIONAL | server | admin | Sender identity for app-owned transactional flows. | A verified sender/domain in Resend. |
EMAIL_BRAND_NAME | server | optional | Brand name shown in transactional invitation emails. Falls back to the sender display name. | Your product or company name. |
EMAIL_BRAND_LOGO_URL | server | optional | Absolute or app-relative PNG logo used in transactional invitation emails. | A publicly reachable email-safe logo. |
EMAIL_BRAND_COLOR_* | server | optional | Semantic #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_EMAIL | server | marketing | Primary verified sender address for Marketing campaigns; generated handler composition falls back to RESEND_FROM_EMAIL. | A verified sender/domain in Resend. |
MARKETING_FROM_NAME | server | marketing | Display name for Marketing campaigns. | Your product or company name. |
RESEND_FROM_MARKETING | server | legacy infra helper | Compatibility value read by getMarketingSender(); new Marketing handlers use MARKETING_FROM_EMAIL. | A verified sender/domain in Resend. |
CONTACT_TO_EMAIL | server | admin | Destination inbox for app-owned contact notifications. | Inbox address owned by the client. |
RESEND_WEBHOOK_SECRET | server | marketing | Svix secret used to verify inbound Resend webhook signatures. | The webhook secret configured in Resend. |
MARKETING_WORKER_SECRET | server | marketing | Shared bearer secret for the internal Marketing worker endpoint. | A project-owned random secret. |
MARKETING_TEST_EMAIL | server | optional Marketing operation | Default 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 usesupabase.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-managementinside a Next.js server runtime, or its/nodesubpath 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. syncSupabaseAuthEmailTemplatesrequires anonBackupcallback 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 capturedrollbackPayloadrestores 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.
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, andapp/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.tsandconfig/modules.ts
Validate after editing .env.local
For platform apps:
- Run the app locally.
- Open
/. - Run the build, then validate
/crmor/admin/userswhen those package mounts are enabled. - Confirm the starter reports the expected readiness state.
- 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.