@stackra/brand

Brand identity runtime for the Stackra framework — writes name, tagline, description, favicon, Open Graph tags, Twitter Cards, and a JSON-LD Organization block from a typed IBrandMetadata bag.

Companion to @stackra/theming. Brand owns identity (name, description, logo assets, favicon, OG tags); theming owns visual tokens (colors, radius, fonts).

Install

Workspace consumer:

{
  "peerDependencies": {
    "@stackra/brand": "workspace:^",
  },
}

Usage

// src/app.module.ts
import { WebBrandModule } from "@stackra/brand/react";

@Module({
  imports: [
    WebBrandModule.forRoot({
      metadata: {
        name: "Academorix",
        tagline: "Sports academy platform",
        description: "Coach every athlete like they're your best.",
        url: "https://academorix.com",
        assets: {
          logotipo: { src: "/logo.svg", alt: "Academorix", width: 128, height: 32 },
          isotipo: { src: "/mark.svg", alt: "Academorix", width: 32, height: 32 },
          favicon: "/favicon.ico",
          ogImage: "/og-image.png",
        },
      },
    }),
  ],
})
export class AppModule {}

Then in main.tsx, immediately after ApplicationFactory.create(...):

const app = await ApplicationFactory.create(AppModule, config);
app.container.get<BrandService>(BRAND_SERVICE).applyDocumentMetadata();
// React mounts...

React helpers

import { BrandLogo, BrandMark, useBrand } from "@stackra/brand/react";

function Header() {
  return <header><BrandMark height={32} /></header>;
}

function Footer() {
  const brand = useBrand();
  return <footer>© {new Date().getFullYear()} {brand.name}</footer>;
}

Runtime overrides

When the backend returns a tenant-scoped brand override:

const brand = container.get<BrandService>(BRAND_SERVICE);
brand.applyPayload({
  metadata: {
    name: "Skyline FC Academy",
    assets: { logotipo: { src: "/tenants/skyline/logo.svg" } },
  },
});

Overrides shallow-merge one level deep on nested groups (assets, organization, twitter) — passing just assets.favicon preserves assets.logotipo.

Testing

import { TestBrandBindings } from "@stackra/brand/testing";
import { BrandService } from "@stackra/brand";

const bindings = new TestBrandBindings();
const service = new BrandService(config, bindings);

service.applyDocumentMetadata();

expect(bindings.calls.titles).toEqual(["Academorix — Sports academy platform"]);
expect(bindings.calls.favicons).toEqual(["/favicon.ico"]);

Related

• @stackra/theming — the sibling package for visual tokens.
• Contracts — every interface + token this package consumes.
• Plan — the design record for the brand + theming split.

License

MIT © Figentra L.L.C.