I've white-labeled the same CRM codebase 7 times for 7 di...

This is the pattern I wish someone had handed me two years ago when I was still git-branching every client into their own forked repo (yes, really, it was as bad as it sounds). One client needs different colors. Another needs their logo on the login screen. A third wants to hide the entire invoicing module because they only use it for lead capture. If you fork the core for each of those, you're signing up to merge bug fixes across 7 repos forever.

Don't do that. Here's what I do instead.

The mental model: core stays sacred, everything else is config

The trick is treating your CRM as two things stacked on top of each other:

Core app code. Routes, business logic, database schema. Untouchable. Same for every tenant.
A branding + feature override layer. Env vars, CSS tokens, email templates, assets, feature flags. This is the ONLY thing that changes between deployments.

When I onboard a new white-label client, I clone the same repo, drop in a new .env, swap a few files in /public/brand/, flip a couple flags, and ship. No git diff against the core. Ever.

Let me walk you through each layer.

Step 1: environment-based branding

This is where most people start, and most people stop. The env file is doing way more work than just storing API keys.

# .env.production (client A: Apex Plumbing)
NEXT_PUBLIC_APP_NAME="Apex CRM"
NEXT_PUBLIC_APP_DOMAIN="crm.apexplumbing.com"
NEXT_PUBLIC_SUPPORT_EMAIL="help@apexplumbing.com"
NEXT_PUBLIC_BRAND_PRIMARY="#0F4C81"
NEXT_PUBLIC_BRAND_ACCENT="#F4A300"
NEXT_PUBLIC_LOGO_PATH="/brand/apex/logo.svg"
NEXT_PUBLIC_FAVICON_PATH="/brand/apex/favicon.ico"
NEXT_PUBLIC_LOGIN_BG="/brand/apex/login-bg.jpg"

Same repo, different .env:

# .env.production (client B: Riverside Roofing)
NEXT_PUBLIC_APP_NAME="Riverside HQ"
NEXT_PUBLIC_APP_DOMAIN="hq.riversideroofing.com"
NEXT_PUBLIC_SUPPORT_EMAIL="ops@riversideroofing.com"
NEXT_PUBLIC_BRAND_PRIMARY="#1A3A2A"
NEXT_PUBLIC_BRAND_ACCENT="#C7522A"
NEXT_PUBLIC_LOGO_PATH="/brand/riverside/logo.svg"
NEXT_PUBLIC_FAVICON_PATH="/brand/riverside/favicon.ico"
NEXT_PUBLIC_LOGIN_BG="/brand/riverside/login-bg.jpg"

Then I read those once in a single brand.config.ts so the rest of the app doesn't have to care:

// lib/brand.config.ts
export const brand = {
  appName: process.env.NEXT_PUBLIC_APP_NAME ?? "CRM",
  domain: process.env.NEXT_PUBLIC_APP_DOMAIN ?? "localhost:3000",
  supportEmail: process.env.NEXT_PUBLIC_SUPPORT_EMAIL ?? "",
  colors: {
    primary: process.env.NEXT_PUBLIC_BRAND_PRIMARY ?? "#111111",
    accent: process.env.NEXT_PUBLIC_BRAND_ACCENT ?? "#FF6600",
  },
  assets: {
    logo: process.env.NEXT_PUBLIC_LOGO_PATH ?? "/brand/default/logo.svg",
    favicon: process.env.NEXT_PUBLIC_FAVICON_PATH ?? "/brand/default/favicon.ico",
    loginBg: process.env.NEXT_PUBLIC_LOGIN_BG ?? "/brand/default/login-bg.jpg",
  },
};

Now anywhere in the app, brand.appName and brand.colors.primary just work. No hardcoded strings, no per-client if (tenant === "apex") branches. The core doesn't know who it's deployed for and that's the WHOLE point.

Step 2: theme overrides via CSS variables

Tailwind is fine, but the second you start dynamic theming with pure Tailwind classes you end up with bg-blue-600 hardcoded in 200 components. Don't do that. Bind your brand colors to CSS custom properties at the root, then point Tailwind at those.

/* app/globals.css */
:root {
  --color-brand-primary: 15 76 129;   /* RGB triplet, set at runtime */
  --color-brand-accent: 244 163 0;
  --color-bg: 255 255 255;
  --color-fg: 17 17 17;
}

[data-theme="dark"] {
  --color-bg: 12 12 14;
  --color-fg: 240 240 240;
}

// tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: {
        brand: {
          primary: "rgb(var(--color-brand-primary) / <alpha-value>)",
          accent: "rgb(var(--color-brand-accent) / <alpha-value>)",
        },
        bg: "rgb(var(--color-bg) / <alpha-value>)",
        fg: "rgb(var(--color-fg) / <alpha-value>)",
      },
    },
  },
};

Then in your root layout, you inject the brand colors from the env at runtime so the same JS bundle works for every tenant:

// app/layout.tsx
import { brand } from "@/lib/brand.config";

function hexToRgb(hex: string) {
  const h = hex.replace("#", "");
  const r = parseInt(h.slice(0, 2), 16);
  const g = parseInt(h.slice(2, 4), 16);
  const b = parseInt(h.slice(4, 6), 16);
  return `${r} ${g} ${b}`;
}

export default function RootLayout({ children }) {
  const style = {
    "--color-brand-primary": hexToRgb(brand.colors.primary),
    "--color-brand-accent": hexToRgb(brand.colors.accent),
  } as React.CSSProperties;

  return (
    <html lang="en" style={style}>
      <head>
        <title>{brand.appName}</title>
        <link rel="icon" href={brand.assets.favicon} />
      </head>
      <body>{children}</body>
    </html>
  );
}

bg-brand-primary and text-brand-accent now resolve to whatever the env says. Zero code changes between tenants.

Step 3: email template overrides

This is where I see people fall over. They hardcode "Welcome to MyApp!" into the transactional emails and then have to fork the templates for every client. Same idea as above: read from brand, never hardcode.

// emails/welcome.tsx (using react-email)
import { brand } from "@/lib/brand.config";

export function WelcomeEmail({ firstName }: { firstName: string }) {
  return (
    <Html>
      <Body style={{ backgroundColor: "#f6f6f6" }}>
        <Container>
          <Img src={`https://${brand.domain}${brand.assets.logo}`} width="140" />
          <Heading>Welcome to {brand.appName}, {firstName}.</Heading>
          <Text>
            If you get stuck, hit reply or email {brand.supportEmail}.
          </Text>
          <Text style={{ color: "#888", fontSize: 12 }}>
            Sent by {brand.appName} | {brand.domain}
          </Text>
        </Container>
      </Body>
    </Html>
  );
}

For clients who want truly different copy (not just different branding), I add a thin override directory the build resolves before the default:

/emails
  /default/
    welcome.tsx
    invoice-sent.tsx
  /overrides/
    apex/
      welcome.tsx        <- only the files Apex wants different
    riverside/
      invoice-sent.tsx

Then a tiny resolver picks the override if it exists:

// lib/email/resolve.ts
import { brand } from "@/lib/brand.config";

const tenant = process.env.BRAND_KEY ?? "default";

export async function loadEmail(name: string) {
  try {
    return (await import(`@/emails/overrides/${tenant}/${name}`)).default;
  } catch {
    return (await import(`@/emails/default/${name}`)).default;
  }
}

Default lives in the core. Overrides live in a per-tenant folder. The core never gets touched.

Step 4: asset replacement

Logos, favicons, login backgrounds, OG share images. I keep them all under /public/brand/<key>/ and let the env path point at the right one.

/public
  /brand
    /default/
      logo.svg
      favicon.ico
      login-bg.jpg
      og-image.png
    /apex/
      logo.svg
      favicon.ico
      login-bg.jpg
      og-image.png
    /riverside/
      logo.svg
      ...

Components just reference brand.assets.logo. The build copies the right folder. Done.

One thing that bit me early on: don't forget the OG/Twitter card image. I shipped a client and his Slack previews still showed the default logo for 3 days because I forgot to update app/opengraph-image.tsx. Get it right the first time so you're not chasing it later.

// app/opengraph-image.tsx
import { ImageResponse } from "next/og";
import { brand } from "@/lib/brand.config";

export default async function OG() {
  return new ImageResponse(
    (
      <div style={{ background: brand.colors.primary, display: "flex" }}>
        <h1 style={{ color: "white" }}>{brand.appName}</h1>
      </div>
    ),
    { width: 1200, height: 630 }
  );
}

Step 5: feature flags per tenant

This is the unlock. Some clients want the invoicing module. Some don't. Some want SMS sequences enabled. Some don't have an A2P approval yet so SMS would just error. Feature flags let you toggle entire modules without if (tenant === "x") mess.

// lib/features.ts
export type FeatureKey =
  | "invoicing"
  | "sms_sequences"
  | "pipeline_automations"
  | "client_portal"
  | "ai_replies";

const flagEnv = process.env.NEXT_PUBLIC_FEATURE_FLAGS ?? "";
const enabled = new Set(
  flagEnv.split(",").map((s) => s.trim()).filter(Boolean)
);

export function feature(key: FeatureKey): boolean {
  return enabled.has(key);
}

# Apex .env
NEXT_PUBLIC_FEATURE_FLAGS="invoicing,client_portal,pipeline_automations"

# Riverside .env (no SMS yet, no invoicing)
NEXT_PUBLIC_FEATURE_FLAGS="client_portal,ai_replies"

Then in your nav, your routes, your settings UI...

{feature("invoicing") && (
  <NavItem href="/invoices" icon={Receipt}>Invoices</NavItem>
)}

{feature("sms_sequences") && <SmsSequenceBuilder />}

You can take this further with per-tenant config in your DB if you want flags to be toggleable at runtime. For SMB white-label work, env-level flags are usually enough and they're WAY easier to reason about.

Why I refuse to fork the core

I learned this from a client situation that could've gone really sideways. The setup: one client, two brands. The main brand was established and ranking. The sister brand had ZERO online presence, tumbleweeds-blowing-through-the-desert kind of nothing. We needed to spin up a second tenant fast, borrow from the existing brand's authority to bootstrap the new one, and not babysit two codebases while doing it.

Because the CRM was wired up like the steps above, deploying tenant #2 was literally:

Clone the repo
New .env
New /public/brand/sister/ folder
New deploy on a subdomain
Done

Maybe an hour, most of which was waiting for DNS. If I'd forked, I'd have been merging hotfixes across two repos for the rest of the year while trying to actually run a marketing campaign for the second brand. No thanks.

Forking feels productive in the moment because you can hack on the new client's code without breaking anyone else. But you've just signed yourself up to maintain N repos forever. The override layer takes one weekend to build and saves you that work for the entire lifespan of the product.

The one rule

If you find yourself reaching for git checkout -b client-acme to add a brand-specific feature... stop. Go back to the override layer and ask "is this a config thing, an asset thing, an email thing, or a feature flag thing?" 95% of the time, the answer is one of those four and your core never needs to know the client exists.

The other 5% is where you have an honest conversation with the client about whether the customization is worth the complexity, or whether they should just use the product as it stands. (Spoiler: it almost always is the latter, they just haven't been told no yet.)

My CRM source code ships with this override layer built in: env-driven branding, CSS-variable theming, email overrides, asset folders, and the feature flag system above, all already wired up. Link in profile if you want to see how it's structured.

推荐订阅源

DEV Community