Using BrightWeb Modules
This page explains how the shared BrightWeb modules are consumed in a generated app.
The shared modules are currently consumed through:
- package entrypoints
- generated scaffold wiring
- server-side page helpers
- shell registration objects
- a small number of route handlers
Use this page together with the per-module pages when you need to answer both of these questions:
- What does this module install?
- How do I actually use it in an app?
Use Base Contract for the support-tier rules and base-contract.json when you need the canonical machine-readable inventory.
Integration model
In a generated platform app, module usage usually happens in 3 places:
config/modules.tsdecides which modules are enabled.config/shell.tswires each enabled module registration into@brightweblabs/app-shell.- App routes call the module package directly for server data, route handlers, or auth helpers.
That means BrightWeb module usage is primarily a package and wiring model. The stable base contract sits inside that model, but this page is focused on how those pieces get used in a real app.
Typical entrypoints
| Package | Typical entrypoints | Support tier | What you use them for |
|---|---|---|---|
@brightweblabs/core-auth/shared | AUTH_RESEND_COOLDOWN_SECONDS, validateEmail(), validatePassword(), buildSignupCallbackUrl(), buildResetPasswordRedirectUrl() | stable | Shared auth validation, constants, and URL derivation. |
@brightweblabs/core-auth/client | useCooldownTimer() | stable | Client-side auth UI behavior such as resend cooldowns. |
@brightweblabs/core-auth/server | requireServerPageAccess(), requireServerPageRoleAccess(), getServerAccess() | stable | Server-side auth and role gating in pages, layouts, and handlers. |
@brightweblabs/infra/server | resendApiRequest(), verifyResendWebhookSignature(), getTransactionalSender(), getMarketingSender(), getContactDestination(), getResendWebhookSecret() | stable | Canonical app-owned Resend transport and webhook verification helpers. |
@brightweblabs/infra/client | createBrowserSupabaseClient() | stable | Browser Supabase client with BrightWeb environment resolution. |
@brightweblabs/infra/realtime | subscribeToAppActivityEvents() | stable | Authenticated, domain-filtered activity invalidation hints. |
@brightweblabs/infra/request-observability | createLatestRequestController(), observedFetch(), appendServerTiming() | stable | Abort stale collection requests and record privacy-safe client/server timing. |
@brightweblabs/infra/robustness | publicError(), readPublicError(), sanitizePublicError(), validateBoundedUuidBatch() | stable | Public error envelopes and bounded mutation validation. |
@brightweblabs/module-admin | listAdminUsers(), handleAdminUsersGetRequest(), handleAdminUsersRoleChangeRequest() | stable | Reusable admin listing plus package-owned admin HTTP handlers. |
@brightweblabs/module-admin | invitation list/create/revoke/accept/registration helpers and handlers | stable | Fourteen-day portal invitations for client, staff, and admin roles. Client invitations do not require an organization. |
@brightweblabs/module-admin | getAdminUsersPageData() | starter | Starter admin page payload for the scaffolded users screen. |
@brightweblabs/module-admin/registration | adminModuleRegistration | stable | Admin app-shell navigation and toolbar registration. |
@brightweblabs/module-admin/ui | AdminUsersClient, AdminToolbarControls, createAdminUiClient() | stable | Packaged users, roles, invitations, and shell toolbar UI with injectable data access. |
@brightweblabs/module-admin/tokens.css | Admin UI tokens and parity classes | stable | Required visual contract for the packaged Admin UI. |
@brightweblabs/module-orgs | listOrganizations(), createOrganization(), updateOrganization(), listOrganizationMembers(), setOrganizationMemberRole() | stable | Shared organization and membership data operations used by CRM and Projects. |
@brightweblabs/module-orgs/ui | OrganizationCreateSheet | stable | Shared organization-creation sheet with optional member invitations for CRM, Projects, and app-owned flows. |
@brightweblabs/module-orgs/registration | orgsModuleRegistration | stable | Hidden foundation registration with no navigation. |
@brightweblabs/module-crm | listCrmContacts(), listCrmOrganizations(), getCrmContactStatusStats(), listCrmOwnerOptions(), listCrmPrimaryContacts(), listCrmStatusTimeline() | stable | Reusable CRM primitives for package-owned CRM surfaces and workflows. |
@brightweblabs/module-crm | handleCrmContactsGetRequest(), handleCrmOrganizationsGetRequest(), handleCrmStatsGetRequest(), handleCrmOwnersGetRequest() | stable | Package-owned CRM GET handlers that can be mounted directly from Next.js routes. |
@brightweblabs/module-crm | getCrmDashboardData() | starter | Starter CRM dashboard payload for the scaffolded CRM page. |
@brightweblabs/module-crm/registration | crmModuleRegistration | stable | CRM app-shell navigation groups and toolbar registration. |
@brightweblabs/module-marketing | campaign, workflow, analytics, webhook, and handler-composition helpers | stable | Consent-aware marketing domain behavior and package-owned HTTP composition. |
@brightweblabs/module-marketing/server | topics, subscriptions, suppressions, and unsubscribe helpers | stable | Consent and contact communication preferences. |
@brightweblabs/module-marketing/campaigns | campaign CRUD, recipient expansion, scheduling, sending, retry, and test delivery | stable | Campaign lifecycle and delivery orchestration. |
@brightweblabs/module-marketing/ui | MarketingClient, MarketingUiProvider, createMarketingUiClient(), MarketingToolbarControls | starter | Package-owned marketing workspace with injectable data access. |
@brightweblabs/module-marketing/registration | marketingModuleRegistration | stable | Marketing navigation and toolbar registration. |
@brightweblabs/module-projects | listProjects(), getProjectPortfolioStats(), getProjectDashboard(), listProjectTasks(), listProjectMilestones(), listProjectLinks(), listClientProjects(), getClientProject() | stable | Reusable internal project workspaces plus narrow client-safe account reads. |
@brightweblabs/module-projects | createProject(), createProjectOrganization(), updateProject(), deleteProject(), createProjectTask(), updateProjectTask(), deleteProjectTask(), createProjectMilestone(), updateProjectMilestone(), deleteProjectMilestone(), createProjectLink(), updateProjectLink(), deleteProjectLink(), listProjectAssignableProfiles(), syncProjectMembers(), listOrgAdminProjectsByProfile() | stable | App-owned project write flows and assignment helpers. |
@brightweblabs/module-projects | getProjectsPortfolioPageData() | starter | Starter portfolio payload for the scaffolded projects page. |
@brightweblabs/module-projects/registration | projectsModuleRegistration | stable | Projects app-shell navigation and toolbar registration. |
For the full symbol-level classification, including internal exports that are visible in source but not part of the supported promise, use base-contract.json.
Common usage patterns
1. Read module data in a server route or page
The current starters call the module packages directly from server pages.
export const dynamic = "force-dynamic";
export default async function CrmPage() {
const { getCrmDashboardData } = await import("@brightweblabs/module-crm");
const data = await getCrmDashboardData();
return <pre>{JSON.stringify(data.stats, null, 2)}</pre>;
}
The same pattern exists for the Projects and Admin starters:
const { getProjectsPortfolioPageData } = await import("@brightweblabs/module-projects");
const portfolio = await getProjectsPortfolioPageData();
import { requireServerPageRoleAccess } from "@brightweblabs/core-auth/server";
export default async function ProjectPage({ params }: { params: { projectId: string } }) {
const { supabase } = await requireServerPageRoleAccess(["admin", "staff"]);
const { getProjectDashboard } = await import("@brightweblabs/module-projects");
const project = await getProjectDashboard(supabase, params.projectId);
return <pre>{JSON.stringify(project.project, null, 2)}</pre>;
}
const { getAdminUsersPageData } = await import("@brightweblabs/module-admin");
const { users } = await getAdminUsersPageData();
Use these helpers when you want the package to own the initial query and normalization logic. Then build your own UI on top of the returned data.
If you need a longer-lived reusable surface, prefer the stable helpers from the manifest over starter page helpers.
For CRM specifically, the stable path is now the smaller helper set:
const [contacts, organizations, stats, owners] = await Promise.all([
listCrmContacts(supabase, { page: 1, pageSize: 50 }),
listCrmOrganizations(supabase, { page: 1, pageSize: 20 }),
getCrmContactStatusStats(supabase),
listCrmOwnerOptions(supabase),
]);
2. Register module navigation and toolbar behavior in the shell
If your app uses @brightweblabs/app-shell, wire the module registrations into your shell config.
import type { ShellContextualAction, ShellModuleRegistration } from "@brightweblabs/app-shell";
import { crmModuleRegistration } from "@brightweblabs/module-crm/registration";
import { marketingModuleRegistration } from "@brightweblabs/module-marketing/registration";
import { projectsModuleRegistration } from "@brightweblabs/module-projects/registration";
import { adminModuleRegistration } from "@brightweblabs/module-admin/registration";
const dashboardModuleRegistration: ShellModuleRegistration<ShellContextualAction> = {
key: "dashboard",
placement: "primary",
navItems: [{ href: "/dashboard", label: "Dashboard" }],
};
const modules = [
dashboardModuleRegistration,
crmModuleRegistration,
marketingModuleRegistration,
projectsModuleRegistration,
adminModuleRegistration,
];
This is the current mechanism for getting module-owned nav items, nav groups, and toolbar route/action registration into the platform shell.
The CRM dashboard follows the MQ shell contract: search, filters, and create actions are not duplicated inside the page. Render CrmToolbarControls for the crm toolbar surface (or compose the exported CrmToolbarSearchChip, CrmToolbarFiltersPill, and CrmToolbarCreateMenu controls individually). A standalone CrmDashboard remains usable for table, dialog, timeline, and organization interactions, but its shell-owned search/filter/create controls are intentionally absent.
3. Mount starter API routes by delegating to package handlers
Admin and CRM expose route-handler helpers that can be re-exported from your Next.js route files.
export const dynamic = "force-dynamic";
export async function GET(request: Request) {
const { handleAdminUsersGetRequest } = await import("@brightweblabs/module-admin");
return handleAdminUsersGetRequest(request);
}
export const dynamic = "force-dynamic";
export async function POST(request: Request) {
const { handleAdminUsersRoleChangeRequest } = await import("@brightweblabs/module-admin");
return handleAdminUsersRoleChangeRequest(request);
}
Use this pattern when a package already owns the HTTP handling contract and your app just needs to mount it under a route.
CRM follows the same pattern:
export const dynamic = "force-dynamic";
export async function GET(request: Request) {
const { handleCrmContactsGetRequest } = await import("@brightweblabs/module-crm");
return handleCrmContactsGetRequest(request);
}
The current CRM starter mounts these package-owned GET handlers at:
/api/crm/contacts/api/crm/organizations/api/crm/stats/api/crm/owners
4. Consume auth from the shared, client, and server entrypoints
The auth package is intentionally split by runtime.
Shared helpers
import {
AUTH_RESEND_COOLDOWN_SECONDS,
buildResetPasswordRedirectUrl,
buildSignupCallbackUrl,
validateEmail,
validatePassword,
} from "@brightweblabs/core-auth/shared";
Client hooks
import { useCooldownTimer } from "@brightweblabs/core-auth/client";
const cooldown = useCooldownTimer(AUTH_RESEND_COOLDOWN_SECONDS);
Server guards
import { requireServerPageAccess, requireServerPageRoleAccess } from "@brightweblabs/core-auth/server";
const { supabase, user, profileId } = await requireServerPageAccess();
const adminAccess = await requireServerPageRoleAccess("admin");
Use shared for runtime-independent logic, client for React hooks, and server for page and route protection.
5. Use infra transport helpers for app-owned email flows
For app-owned email behavior (contact forms, invites, campaigns, and webhook verification), use @brightweblabs/infra/server.
import {
getMarketingSender,
resendApiRequest,
verifyResendWebhookSignature,
} from "@brightweblabs/infra/server";
Auth email flows should stay on supabase.auth.* and Supabase Auth SMTP/project settings.
Module-specific usage notes
Platform Base
- Use
@brightweblabs/core-auth/serverto gate pages and get the current signed-in user context. - Use
@brightweblabs/core-auth/sharedfor validation and callback URL helpers. - Use
@brightweblabs/module-adminfor admin user listing, role changes, handlers, and the mountableAdminUsersPage. - Use
@brightweblabs/module-admin/uiwhen an app needs to inject its own users/invitations client or composeAdminToolbarControlsintoAppHeader.
CRM
- Build on
listCrmContacts(),getCrmContactStatusStats(),listCrmStatusTimeline(),listCrmPrimaryContacts(), andlistCrmOwnerOptions()when you need reusable CRM data primitives. - Import
listOrganizations()from@brightweblabs/module-orgsfor new organization lists;listCrmOrganizations()remains as a compatibility alias. - Load only the CRM slices a page needs. For example, a contacts-first page can skip
listCrmOwnerOptions()andlistCrmPrimaryContacts()until an assignment or organization-edit workflow needs them. - Mount the package-owned CRM GET handlers when you want the package to own the initial HTTP contract.
- Treat
getCrmDashboardData()asstarterpage glue for the scaffolded CRM screen. - Build reusable forms, tables, actions, and workflows in the CRM package, then keep the app route as a thin mount.
Marketing
- Mount
MarketingPagefor the complete staff workspace or injectcreateMarketingUiClient()into package UI surfaces. - Keep Resend credentials, worker secrets, and webhook secrets in the generated server-only
_handlers.tscomposition. - Use the domain subpaths for custom products:
/serverfor consent,/campaignsfor campaign lifecycle,/segmentsfor audiences,/workerfor bounded delivery, and/emailfor the injected sender. - Treat the generated worker, webhook, and unsubscribe routes as one operational unit; a campaign UI without those routes is not a complete delivery installation.
- Follow Marketing Delivery & Scheduler before enabling production sends.
Projects
- Build on
listProjects()andgetProjectPortfolioStats()when you need reusable project listing and metrics helpers. - Use
getProjectDashboard()for internal detail views. Client-facing routes must uselistClientProjects()andgetClientProject(); never project the full internal dashboard into a client response. - Use the task, milestone, link, and member helpers when your app owns project write flows.
- Treat
getProjectsPortfolioPageData()asstarterpackage glue. New scaffolds mount package-owned Projects UI through@brightweblabs/module-projects/routes; host apps can use those route components directly or build custom pages on the lower-level helpers. - Use
@brightweblabs/module-projects/route-handlersfor thin generated API routes and the package-roothandle*Request()exports when composing host-owned request behavior. - Use
projectsModuleRegistrationwhen you want project navigation and toolbar behavior in the shell.
Related contract docs
- Base Contract defines the support tiers.
- base-contract.json is the canonical symbol inventory.
- The module pages explain what each module installs, what is stable, and what is only starter scaffolding.
Related docs
Implementation references
packages/core-auth/src/shared.tspackages/core-auth/src/client.tspackages/core-auth/src/server.tspackages/module-admin/src/index.tspackages/module-admin/src/registration.tspackages/module-crm/src/index.tspackages/module-crm/src/registration.tspackages/module-projects/src/index.tspackages/module-projects/src/registration.tspackages/create-bw-app/template/modules/admin/app/api/admin/users/route.tspackages/create-bw-app/template/modules/admin/app/api/admin/users/roles/route.tspackages/create-bw-app/template/modules/crm/app/api/crm/contacts/route.tspackages/create-bw-app/template/modules/crm/app/api/crm/organizations/route.tspackages/create-bw-app/template/modules/crm/app/api/crm/stats/route.tspackages/create-bw-app/template/modules/crm/app/api/crm/owners/route.tspackages/create-bw-app/template/modules/admin/app/admin/users/page.tsxpackages/create-bw-app/template/modules/crm/app/crm/page.tsxapps/platform-preview/config/shell.ts