Overview

lib-source-web is the single source of truth for UI components, themes, and utilities shared across Vodafone's digital products — including the Vodafone shop, My Vodafone (ecare), business products (ebu), VOXI, Three (vf3), and the content management system (scms).

All packages are published to a private Azure DevOps npm registry under three scopes: @source-web/* (shared core), @vfuk/* (VFUK-specific), and @vf/* (VF brand).

Guided Tour — Start Here

If you're new, read in this order. Each section builds on the last.

Persona Quick-Links

Getting Started

Prerequisites

• Node.js ≥ 22 — the JavaScript runtime. Download from nodejs.org.
• pnpm 10.33.2 — the package manager (like npm but faster and monorepo-aware). Install: npm install -g pnpm@10.33.2
• Private registry access — all @source-web/*, @vfuk/*, @vf/* packages live on Azure DevOps, not public npm. Ask the team for .npmrc credentials.

Installation

# 1. Clone the repo (via Azure DevOps)
git clone https://vfuk-digital@dev.azure.com/vfuk-digital/Digital/_git/lib-source-web
cd lib-source-web

# 2. Install all workspace dependencies (reads .npmrc for private registry)
pnpm install

# 3. Build every package in topological order, then start the docsite
pnpm start
# Docsite opens at http://127.0.0.1:6069/

→ See: package.json for full scripts list.

Faster daily workflow (after first install)

# Start just the docsite (no rebuild — assumes packages are already built)
pnpm start:docsite

# Build only packages changed since main branch
pnpm build:changes

# Run tests for changed packages only
pnpm test:preMerge

# Work on a single package
pnpm nx run @source-web/button:build
pnpm nx run @source-web/button:test

Command Cheat Sheet

Daily workflow

Linting (the four checks preMerge runs)

Generators & housekeeping

Environment Variable Reference

What is a Monorepo?

How the workspace is structured

pnpm-workspace.yaml tells pnpm which folders are packages. Any folder with a package.json inside packages/**/** or docs/**/** is automatically part of the workspace.

Workspace dependencies — workspace:*

When one package depends on another in the same repo, it uses "workspace:*" as the version. This means "use the local copy, whatever version it's at." No publishing to npm required during development.

// Button's package.json — depends on Icon and Interaction from the same repo
"peerDependencies": {
  "@source-web/icon": "workspace:*",
  "@source-web/interaction": "workspace:*"
}

Package scopes explained

Nx — Smart Build System

The three things Nx does here

1. Topological build ordering

In nx.json, the build target has "dependsOn": ["^build"]. The ^ means "all of my dependencies must build first." So if Button depends on Icon and Interaction, Nx builds those before Button — automatically.

// nx.json
"build": {
  "dependsOn": ["^build"],   // ^ = upstream packages first
  "outputs": ["{projectRoot}/dist"],
  "cache": true
}

2. Computation caching

Every cacheable task (build, test, lint) stores its result. Next time you run the same task on unchanged files, Nx replays the cached result instantly — no re-running. Cache key = input files + env + command.

# First run: compiles all 476 packages (~5 min)
pnpm build:all

# Second run (nothing changed): replays cache (~5 sec)
pnpm build:all
# Output: "476 tasks from cache"

3. Affected detection

nx affected compares your branch against main and finds every package whose source files changed — plus every package that depends on those packages. Only those packages are rebuilt/tested.

# Only build packages changed since main (and their dependents)
pnpm build:changes

# Only run tests for affected packages
pnpm test:preMerge

# Run all pre-merge checks (build + lint + test) for affected only
pnpm preMerge

Key Nx commands

Architecture & Request Flow

Walking through the diagram

1. Product App wraps its tree in <SourceProvider theme={ws10Theme}>. This is the single setup step every consuming app must do.
2. SourceProvider injects ThemeProvider (from styled-components) — this makes the theme object available to every styled component in the tree via React context.
3. SourceProvider injects I18nextProvider — internationalisation (English, Italian, Spanish) for any component that uses translated strings.
4. SourceProvider injects OverlayProvider — manages z-index stacking for modals, drawers, and flyouts.
5. Theme flows down to components — any styled-component can read props.theme to get the active brand's colour tokens.
6. Component reads its own theme file — e.g. Button.theme.ts maps abstract token keys (theme.color.primary1.default) to the component's visual properties (background, text, border colour).
7. Brand theme provides the tokens — @source-web/theme-ws10 defines what color.primary1.default actually is (Vodafone Red: #e60000). Swap to @source-web/theme-three and the same token becomes Three's brand colour.

How a component is consumed by a product team

// In a product app (e.g. shop.vodafone.co.uk)
import { SourceProvider } from '@source-web/source-provider'
import ws10Theme from '@source-web/theme-ws10'
import { Button } from '@source-web/button'

// 1. Wrap at app root
function App() {
  return (
    <SourceProvider theme={ws10Theme}>
      <MyRouter />
    </SourceProvider>
  )
}

// 2. Use components anywhere in the tree — theme is automatic
function CheckoutPage() {
  return <Button text="Buy Now" appearance="primary" onClick={handleBuy} />
}

→ See: SourceProvider.tsx

Package Anatomy — The Button Package

Complete file tree

The six key source files explained

// Button.tsx (simplified)
const Button: FC<ButtonProps> = ({ appearance = 'primary', loading = false, text, icon, state, ... }) => {
  const buttonTheme = useLocalTheme('Button', defaultTheme, localTheme)
  // useLocalTheme: merges the brand theme with any component-level overrides

  return loading ? (
    <Styled.Button ...>
      <LoadingSpinner />           {/* spinner overlays the text */}
      <Styled.HiddenText>{text}</Styled.HiddenText>  {/* text hidden but readable by screen readers */}
    </Styled.Button>
  ) : (
    <Styled.Button ...>{text}</Styled.Button>
  )
}

export interface ButtonProps extends BaseButtonWithIconProps, BaseProps<ButtonTheme, AppearanceKeys> {
  width?: 'auto' | 'full'    // auto (default) or full-width
  inverse?: boolean           // inverted colour scheme for dark backgrounds
}
// BaseProps adds: localTheme, dataAttributes, dataSelectorPrefix, id

// Button.style.ts (simplified)
export const Button = styled(Interaction)<StyledButtonProps>((props) => {
  const themeAppearance = props.buttonTheme.appearance[props.appearance]
  return css`
    height: 44px;
    min-width: 152px;
    color: ${themeAppearance.color};              // from component theme
    background: ${themeAppearance.backgroundColor};
    border-radius: ${props.buttonTheme.borderRadius}; // from component theme
    ${respondTo.md(css`width: ${props.width === 'auto' ? 'auto' : '100%'}`)}
    &:hover { background: ${themeAppearance.hover.backgroundColor}; }
  `
})

const defaultTheme = (theme: Theme): ButtonTheme => ({
  appearance: {
    primary: {
      color: theme.color.monochrome1.default,       // white text
      backgroundColor: theme.color.primary1.default, // brand red (e60000 for WS10)
      borderColor: theme.color.primary1.default,
      hover: { backgroundColor: theme.color.primary1.hover },
      // ... inverse variants, pressed states ...
    },
    secondary: { ... },
    alt1: { ... },   // ghost button (transparent bg, solid border)
    alt2: { ... },   // ghost button (red border)
  },
  borderRadius: theme.border.radius[2],
  fontWeight: theme.fontWeight[2],
})

{
  "name": "@source-web/button",
  "version": "15.1.0",
  "type": "module",           // ESM-only
  "module": "dist/index.mjs", // the built file consuming apps import
  "types": "dist/index.d.mts",
  "figma": { "fileId": "w1DKMfwVkHuSKjZqhii4vc", "nodeId": "4824-264641" },
  "packageStatus": { "dev": "stable", "ux": "stable" },
  "tags": {
    "category": "interactions",
    "channel": "core",
    "themes": ["ws10", "voxi", "voxi3", "vf3"]  // which themes this component supports
  }
}

tsdown — The Bundler

The base config (shared by every package)

Every package's tsdown.config.ts is just two lines — it extends the central config from @source-web/style-guide:

// packages/core/interactions/Button/tsdown.config.ts
import { defineConfig } from 'tsdown'
import baseConfig from '@source-web/style-guide/tsdown'
export default defineConfig(baseConfig)

The base config itself lives at packages/core/tools/styleGuide/src/tsdown/index.ts:

// @source-web/style-guide/tsdown (the actual base)
const config: UserConfig = {
  attw: true,              // "Are The Types Wrong?" — validates exported types are correct
  dts: { tsgo: true },     // Generate .d.mts declarations using tsgo (faster than tsc)
  entry: { index: 'src/index.ts' },  // Single entry: always src/index.ts
  format: ['esm'],         // Output ES Modules only — no CommonJS, no UMD
  publint: true,           // Validate package.json exports before publish
}

What each option means

Build output

dist/
├── index.mjs      ← the compiled component (what apps import)
└── index.d.mts    ← TypeScript types (what your editor uses for autocomplete)

Linting Stack

The four linters

# Run for the whole repo
pnpm lint:oxlint

# Run for one package
pnpm nx run @source-web/button:lint:oxlint

# Check formatting (CI — fails if code isn't formatted)
pnpm lint:oxfmt

# Auto-fix formatting (local — modifies files)
pnpm nx run @source-web/button:fmt

pnpm lint:stylelint

pnpm lint:ts

depcheck — dependency hygiene

depcheck scans each package for dependencies that are declared in package.json but never actually imported, and imports that exist in the code but aren't declared. Keeps package.json accurate.

pnpm lint:depcheck

The central config hub: @source-web/style-guide

Every linting/formatting config in every package is a one-liner that extends @source-web/style-guide. Changing a rule in the style-guide propagates to all 476 packages automatically on next build.

// Any package's oxlint.config.ts — always this pattern
import { defineConfig } from 'oxlint'
import reactConfig from '@source-web/style-guide/oxlint/react'
export default defineConfig(reactConfig)

→ See: @source-web/style-guide package.json

Theme System

Theme packages

How tokens flow

// 1. Brand theme defines tokens
// @source-web/theme-ws10/src/constants/colors.ts
export const primary1 = { default: '#e60000', hover: '#bd0000', pressed: '#990000' }

// 2. Component theme maps tokens to visual properties
// Button.theme.ts
primary: {
  backgroundColor: theme.color.primary1.default, // '#e60000' for WS10
  hover: { backgroundColor: theme.color.primary1.hover } // '#bd0000'
}

// 3. Styled component reads at render time
// Button.style.ts
background: ${themeAppearance.backgroundColor}; // renders '#e60000'

The useLocalTheme hook

Components call useLocalTheme('Button', defaultTheme, localTheme). This merges the brand's global theme with the component's default theme, then applies any localTheme prop passed by the consumer. This lets a product team customise one button's appearance without overriding the global brand theme.

// Product team customising a specific button instance
<Button
  text="Special Offer"
  localTheme={(theme) => ({ appearance: { primary: { backgroundColor: theme.color.success.default }}})}
/>

Theming primitives (packages/core/theming/)

These packages define the shape of theme objects — the TypeScript interfaces that all brand themes must conform to:

Infrastructure Packages

These packages aren't UI components — they're the foundational building blocks every component depends on. They live in packages/core/misc/, packages/core/tools/, and packages/core/styles/.

<SourceProvider theme={ws10Theme} baseAssetUrl="https://cdn.vodafone.co.uk/">
  <App />
</SourceProvider>

// Interaction automatically picks the right HTML element:
// href="..." → renders as <a href="...">
// type="submit" → renders as <button type="submit">
// customRouterProps → renders as your router's Link component

interface ButtonProps extends BaseProps<ButtonTheme, AppearanceKeys> {
  // BaseProps adds: localTheme, dataAttributes, dataSelectorPrefix, id
  text: string
  appearance?: 'primary' | 'secondary' | 'alt1' | 'alt2'
}

import { respondTo, spacing, advancedSpacing, opacity, transition } from '@source-web/mixins'

// respondTo.md() → @media (min-width: 768px) { ... }
${respondTo.md(css`width: auto`)}

// spacing('margin', 3) → margin: 12px (3 × 4px base unit)
${spacing('margin', 3)}

// advancedSpacing('padding', [3, 5]) → padding: 12px 20px
${advancedSpacing('padding', [3, 5])}

Core Component Categories

All shared components live under packages/core/ and are organised into 39 functional categories. Every package in this folder is scoped @source-web/* and usable by all product teams.

Adding a New Component

Scenario: Adding a Badge component

We want to create a new @source-web/badge-count component — a circular number badge (like a notification count) that sits on top of other UI elements.

This follows the exact same pattern as every existing component. The walkthrough below reflects how a component like @source-web/number-badge (which already exists) was created.

pnpm packageGenerator

? Select the type of package        → Component
? What will the package be called?  → BadgeCount
? Component channel                 → core
? Component category                → badges
? Theme(s)                          → ws10, voxi, voxi3, vf3
? Does your component have a Figma URL? → Yes
? Enter Figma URL here:             → https://www.figma.com/file/...
? Publish as a pre-release?         → No

// src/BadgeCount.tsx
import { useLocalTheme } from '@source-web/themes'
import * as Styled from './styles/BadgeCount.style'
import defaultTheme from './themes/BadgeCount.theme'
import type { BadgeCountProps } from './BadgeCount.types'

const BadgeCount: FC<BadgeCountProps> = ({ count, appearance = 'primary', localTheme }) => {
  const theme = useLocalTheme('BadgeCount', defaultTheme, localTheme)
  return <Styled.Badge theme={theme} appearance={appearance}>{count}</Styled.Badge>
}
export default BadgeCount

// src/BadgeCount.types.ts
export interface BadgeCountProps extends BaseProps<BadgeCountTheme, AppearanceKeys> {
  count: number        // the number to display
  appearance?: 'primary' | 'secondary'
}

// src/styles/BadgeCount.style.ts
export const Badge = styled.span<StyledBadgeProps>((props) => css`
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 20px;
  height: 20px;
  border-radius: 50%;
  background: ${props.badgeTheme.appearance[props.appearance].backgroundColor};
  color: ${props.badgeTheme.appearance[props.appearance].color};
  font-size: 11px;
  font-weight: ${props.theme.fontWeight[2]};
`)

// src/themes/BadgeCount.theme.ts
const defaultTheme = (theme: Theme): BadgeCountTheme => ({
  appearance: {
    primary: {
      backgroundColor: theme.color.primary1.default,  // brand red
      color: theme.color.monochrome1.default,          // white
    },
    secondary: {
      backgroundColor: theme.color.monochrome5.default,
      color: theme.color.monochrome1.default,
    },
  },
})

// src/examples/01_Appearances.example.tsx
const Appearances = () => (
  <>
    <BadgeCount count={5} appearance="primary" />
    <BadgeCount count={12} appearance="secondary" />
  </>
)
export default Appearances

pnpm exampleGenerator
# Select: @source-web/badge-count

# Build only this package
pnpm nx run @source-web/badge-count:build

# Run unit/integration tests
pnpm nx run @source-web/badge-count:test

# Open Cypress for visual/interaction tests
pnpm nx run @source-web/badge-count:cy:open

pnpm autoVersioner
# Runs: beachball change --fetch
# Prompts for: change type (patch/minor/major) and description
# Creates a .json file in change/ — commit this with your PR

pnpm preMerge
# Runs for affected packages only:
# build → lint:depcheck → fmt:check → lint:stylelint → lint:oxlint → lint:ts → test

Brand-Specific Packages — Overview

ebu — Enterprise Business Unit

// Example: protecting a route with GateKeeper
import { GateKeeper } from '@vfuk/ebu-core-gate-keeper'
<GateKeeper requiredRole="ACCOUNT_MANAGER">
  <ManageContractsPage />
</GateKeeper>

ecare — Customer Care / My Vodafone

// Example: using the page-with-nav layout
import PageWithNav from '@vfuk/ecare-core-components-page-with-nav'
export default function BillPage() {
  return <PageWithNav title="Your Bill"><BillDetails /></PageWithNav>
}

shop — E-commerce

vf3 — Vodafone 3 / Three Brand

import { VF3FrameBanner } from '@source-web/vf3-frame-banner'
<VF3FrameBanner heading="Unlimited data" subheading="On Three's 5G network" />

VF3-Supported Components

The following core components explicitly declare "vf3" in their tags.themes — meaning they have been tested and styled against the Three/VF3 brand theme. Pass @source-web/theme-vf3 to SourceProvider and they will render in Three's visual language automatically.

voxi — VOXI Brand

import { VoxiBanner } from '@source-web/voxi-banner'
<VoxiBanner heading="Endless social data" ctaText="Get VOXI" ctaHref="/voxi" />

scms — Smart Content Management System

// Example: rendering a Contentful Rich Text field
import { ContentfulRichText } from '@source-web/contentful-rich-text'
<ContentfulRichText document={contentfulEntry.fields.body} />

Utility Packages (packages/core/utils/)

Org Resolver — @vf/utils-org-resolver-helpers

Package location

packages/core/utils/orgResolverHelpers/
├── src/
│   ├── orgResolver/             ← core resolution logic
│   │   ├── orgResolver.ts
│   │   └── orgResolver.test.ts
│   ├── isThree/
│   │   ├── isThree.ts
│   │   └── isThree.test.ts
│   ├── isVodafone/
│   │   ├── isVodafone.ts
│   │   └── isVodafone.test.ts
│   ├── getOrgSpaceName/
│   │   ├── getOrgSpaceName.ts
│   │   └── getOrgSpaceName.test.ts
│   ├── getTealiumProfile/
│   │   ├── getTealiumProfile.ts
│   │   └── getTealiumProfile.test.ts
│   ├── loadOrgTheme/
│   │   ├── loadOrgTheme.ts
│   │   └── loadOrgTheme.test.ts
│   ├── constants/
│   │   ├── organisations.ts    ← ORGS, VALID_ORGS, DEFAULT_ORG
│   │   └── tealiumProfiles.ts  ← BASE_TEALIUM_PROFILE, TEALIUM_PROFILES
│   ├── types/
│   │   └── orgResolver.types.ts  ← OrgID, Req
│   └── index.ts                ← public API (all exports)

Constants — organisations.ts

The foundation everything else builds on. Two string constants that identify every valid org:

// src/constants/organisations.ts
import type { OrgID } from '../types/orgResolver.types'

const VODAFONE = 'VFRED'
const THREE = 'VFT03'

export const ORGS = {
  VODAFONE,
  THREE,
} as const

export const VALID_ORGS: string[] = Object.values(ORGS)
// → ['VFRED', 'VFT03']

export const DEFAULT_ORG: OrgID = 'VFRED'
// Falls back to Vodafone if nothing is set

Types — orgResolver.types.ts

// src/types/orgResolver.types.ts

// The only two valid org identifiers in the system
export type OrgID = 'VFRED' | 'VFT03'

// A minimal request-like object — only the cookies bag is needed
// Matches the shape of an Express / Next.js / Node request
export interface Req {
  cookies: Record<string, string>
}

The Req interface is intentionally narrow. The resolver only reads req.cookies, so passing a full Express Request object works — but you could also pass { cookies: req.cookies } if your framework uses a different request shape.

Core function — resolveOrgId

This is the heart of the package. Everything else calls this function. Here is the complete source with annotations:

// src/orgResolver/orgResolver.ts
import getCookie from '@vf/utils-get-cookie'
import VFUK from '@vfuk/utils-get-env-variables'

import { VALID_ORGS, DEFAULT_ORG } from '../constants'
import type { OrgID, Req } from '../types/orgResolver.types'

const ORG_ID = 'ORG_ID'  // the key used for both the env var and the cookie

// Type guard — returns true only if the value is 'VFRED' or 'VFT03'
const isValidOrg = (value: unknown): value is OrgID =>
  typeof value === 'string' && (VALID_ORGS as readonly string[]).includes(value)

export const resolveOrgId = (req?: Req): OrgID => {
  // Step 1: Read env — VFUK is a Vodafone utility that works on both server and client
  const env = VFUK.env as Record<string, unknown> | undefined
  let orgIdValue = env?.[ORG_ID]

  // Step 2: Determine whether we are in a production environment
  const environment = env?.ENVIRONMENT
  const isProduction = typeof environment === 'string' && environment.startsWith('prod')
  // 'prod', 'prod1-green', 'prod2-blue' etc. all count as production

  // Step 3: In NON-PRODUCTION only — attempt cookie override
  if (!isProduction) {
    const cookieValue = getCookie(ORG_ID, req)
    // getCookie handles both server-side (reads from req.cookies) and
    // client-side (reads from document.cookie) via the req parameter
    if (isValidOrg(cookieValue)) orgIdValue = cookieValue
    // Only override if the cookie contains a KNOWN valid org string.
    // An invalid / garbage cookie is silently ignored.
  }

  // Step 4: Return the resolved value, or fall back to Vodafone (VFRED)
  return isValidOrg(orgIdValue) ? orgIdValue : DEFAULT_ORG
}

Resolution order (highest priority first)

What counts as "production"?

isProduction is true when VFUK.env.ENVIRONMENT is a string starting with "prod". This catches all environment names that Vodafone's infrastructure uses for live deployments (prod, prod1-green, prod1-blue, prod2-green, etc.). Staging / integration environments like int1-blue, int2-green, and anything without an ENVIRONMENT variable set (i.e. local development) are treated as non-production.

Test behaviour (from orgResolver.test.ts)

Server-side vs client-side usage

// ── Client-side (runs in the browser) ───────────────────────────────────────
const org = resolveOrgId()
// getCookie reads document.cookie; no req needed

// ── Server-side (runs in Node.js / SSR) ─────────────────────────────────────
const org = resolveOrgId(req)
// Pass the incoming HTTP request so getCookie can read req.cookies
// The req object must conform to the Req interface: { cookies: Record<string, string> }
// A standard Express / Next.js / Fastify request already satisfies this

Setting the cookie for local org switching

// In Chrome DevTools → Application → Cookies, set:
// Name:  ORG_ID
// Value: VFT03        ← Three brand
// Value: VFRED        ← Vodafone brand (or delete the cookie to revert)

// Or from a browser console (non-production only):
document.cookie = 'ORG_ID=VFT03; path=/'

Convenience helper — isThree

A Boolean shorthand for the most common Three-org check. Internally calls resolveOrgId and compares the result.

// src/isThree/isThree.ts
import { ORGS } from '../constants'
import { resolveOrgId } from '../orgResolver'
import type { Req } from '../types/orgResolver.types'

export const isThree = (req?: Req): boolean => {
  return resolveOrgId(req) === ORGS.THREE  // 'VFT03'
}

// Usage
import { isThree } from '@vf/utils-org-resolver-helpers'

// Client-side conditional rendering
if (isThree()) {
  return <ThreeLogo />
}

// Server-side (pass req for cookie support in staging)
const showThreeNav = isThree(req)

The req parameter flows through to resolveOrgId unchanged — the same production/cookie rules apply.

Convenience helper — isVodafone

Mirror of isThree. True when resolveOrgId returns 'VFRED'.

// src/isVodafone/isVodafone.ts
import { ORGS } from '../constants'
import { resolveOrgId } from '../orgResolver'
import type { Req } from '../types/orgResolver.types'

export const isVodafone = (req?: Req): boolean => {
  return resolveOrgId(req) === ORGS.VODAFONE  // 'VFRED'
}

// Usage — equivalent to !isThree() but more readable in Vodafone-specific code paths
if (isVodafone()) {
  loadVodafoneAnalyticsTag()
}

Space name helper — getOrgSpaceName

Vodafone uses "content spaces" — named buckets in the content management system (CMS) — to store copy, assets, and configuration. The space for Three content is always called 'three'. This helper maps any space name to its Three equivalent when running on the Three org.

// src/getOrgSpaceName/getOrgSpaceName.ts
import { ORGS } from '../constants'
import { resolveOrgId } from '../orgResolver'

export const getOrgSpaceName = (originalSpaceName: string): string => {
  return resolveOrgId() === ORGS.THREE ? 'three' : originalSpaceName
}

// Usage — content fetching layer
import { getOrgSpaceName } from '@vf/utils-org-resolver-helpers'

const spaceName = getOrgSpaceName('vodafone')
// → 'three'     when running on Three org
// → 'vodafone'  when running on Vodafone org

const content = await fetchContent(spaceName, pageId)

Note: this helper does not accept a req parameter — it only calls resolveOrgId() with no argument, so it always uses the client-side resolution path. Server-side CMS calls that need cookie support should call resolveOrgId(req) directly and build the space name manually.

Analytics helper — getTealiumProfile

New since the org-resolver rename: resolves the correct Tealium analytics profile for the active org, backed by the BASE_TEALIUM_PROFILE / TEALIUM_PROFILES constants in constants/tealiumProfiles.ts. Same resolution path as everything else — it delegates to resolveOrgId under the hood.

Async theme loader — loadOrgTheme

Dynamically imports the correct theme package at runtime using resolveOrgId. Avoids bundling both theme packages into every app — only the active org's theme is loaded.

// src/loadOrgTheme/loadOrgTheme.ts
import type { Theme } from '@source-web/themes'

import { ORGS } from '../constants'
import { resolveOrgId } from '../orgResolver'

// A lookup map of lazy imports — neither module is loaded until called
const themeImportAsync = {
  [ORGS.VODAFONE]: () => import('@source-web/theme-ws10')  as Promise<{ default: Theme }>,
  [ORGS.THREE]:    () => import('@source-web/theme-three') as Promise<{ default: Theme }>,
} as const

export const loadOrgTheme = async () => {
  const orgId = resolveOrgId()
  const themeModule = await themeImportAsync[orgId]()
  return themeModule.default  // the plain theme object, not the module wrapper
}

// Usage — app bootstrap (e.g. in Next.js _app.tsx or a top-level provider)
import { loadOrgTheme } from '@vf/utils-org-resolver-helpers'
import { SourceProvider } from '@source-web/source-provider'

export default function App({ Component, pageProps }) {
  const [theme, setTheme] = useState(null)

  useEffect(() => {
    loadOrgTheme().then(setTheme)
  }, [])

  if (!theme) return null  // or a skeleton / loading state

  return (
    <SourceProvider theme={theme}>
      <Component {...pageProps} />
    </SourceProvider>
  )
}

Why dynamic import instead of static?

Each theme package (@source-web/theme-ws10, @source-web/theme-three) contains hundreds of design tokens. A static import would bundle both into every app regardless of which org is active, doubling the theme payload for no benefit. The dynamic import pattern means the browser (or Node.js) only fetches the theme for the active org.

Public API — index.ts

Everything the package exports, in one place:

// src/index.ts
export { resolveOrgId as default, resolveOrgId } from './orgResolver'

export { isVodafone } from './isVodafone'
export { isThree } from './isThree'
export { getOrgSpaceName } from './getOrgSpaceName'
export { getTealiumProfile } from './getTealiumProfile'
export { loadOrgTheme } from './loadOrgTheme'

export { ORGS, VALID_ORGS, BASE_TEALIUM_PROFILE, TEALIUM_PROFILES } from './constants'

export type { OrgID, Req } from './types/orgResolver.types'

Which helper to use when

Testing Strategy

// Button.unit.spec.tsx — as generated, never filled in
export const unitTests = (): void => {
  describe('Unit Tests', () => {
    // Write tests below this line
    // End tests above this line
  })
}

The four test layers

Where real vitest unit tests actually live

Pure-logic packages — anything under packages/core/utils/, helpers/, or a component's internal helpers/ subfolder — use plain *.test.ts files with real vitest assertions. This is where the bulk of genuine unit coverage in the repo lives (180+ files at last count), e.g. getCookie.test.ts, getAllFeatureFlags.test.ts. If you're looking for a good test-writing example, start here rather than in a component's tests/unit/ stub.

// getCookie.test.ts — a real vitest unit test
describe('getCookie', (): void => {
  it('returns the correct Cookie value server side, req exists', (): void => {
    const req = { cookies: { basketId: '14caa3b4-fa89-4b43-8264-28f29205ba6a' } }
    const basketId = getCookie('basketId', req)
    expect(basketId).toEqual('14caa3b4-fa89-4b43-8264-28f29205ba6a')
  })

  it("returns null if cookie doesn't exist", (): void => {
    vi.spyOn(isClient, 'default').mockReturnValueOnce(true)
    expect(getCookie('nonExistingCookie')).toEqual(null)
  })
})

How UI tests iterate across themes

The tags.themes array in each package.json tells the UI test which themes to snapshot. The test loops over them automatically:

// Button.ui.spec.tsx (auto-generated by exampleGenerator)
tags.themes.forEach((theme) => {       // ['ws10', 'voxi', 'voxi3', 'vf3']
  describe(`${theme} UI Tests`, () => {
    it('Should take a screenshot', () => {
      cy.vfMount(<Appearances />, { theme, inverse: false })
      cy.vfScreenshot({ pageName: 'Button', theme, testName: 'Appearances' })
      // Percy uploads the screenshot and diffs against baseline
    })
  })
})

Running tests

# All unit tests
pnpm test

# Affected unit tests only (use before PR)
pnpm test:preMerge

# Single package unit tests
pnpm nx run @source-web/button:test

# Open Cypress for a package (interactive mode)
pnpm nx run @source-web/button:cy:open

# Run Cypress in headless mode (CI)
pnpm nx run @source-web/button:cy:run

# Pre-check Cypress before running (checks if tests are needed)
pnpm cy:preRunner

Custom Cypress commands

@source-web/cypress-tools provides shared Cypress commands used in all component tests:

cy.vfMount(component, { theme: 'ws10', inverse: false })
// Mounts a component inside a SourceProvider with the specified theme

cy.vfScreenshot({ cssSelector: '#component-wrapper', pageName, theme, testName })
// Takes a Percy visual snapshot with structured naming

CI/CD pipeline — what actually gates a merge

The pre-merge pipeline lives at cicd/pre-merge/pre-merge-validator.yaml and runs as four sequential Azure DevOps stages:

Practically: running pnpm preMerge locally before pushing mirrors the Validate stage — if it passes locally, the Validate stage should pass in CI too (Cypress visual/a11y specifics aside, since those need the CI environment to run against Percy's baseline).

Versioning & Release

Semantic versioning (semver) rules

# Create a changeset (run after making your code changes)
pnpm autoVersioner
# Prompts: Which packages changed? What type (patch/minor/major)? Description?
# Creates: change/my-package-name-abc123.json
# Commit this file with your PR

# Applied automatically by CI on merge to main:
pnpm bump:packages  # beachball bump --yes

Release internals — why your workspace dependency versions sometimes show x

The repo's beachball.config.js wires up two non-default hooks that run on every release. If you've ever wondered why a package's dependencies field shows something like "@source-web/button": "15.1.x" instead of an exact version, this is why:

• prebump hook — before any version is bumped, it scans every local package and records which internal (@vf/*, @vfuk/*, @source-web/*) dependencies are currently on a prerelease version (e.g. 2.0.0-alpha.3).
• postbump hook — after bumping, it does two things: resets any dependency that was a prerelease back to the stable version it remembers from prebump (so a release never accidentally ships pinned to an alpha), then runs packageDepsToAnyPatch(), which rewrites the exact patch digit of every internal dependency to x — e.g. 15.1.0 becomes 15.1.x.

→ See: beachball.config.js — look for packageDepsToAnyPatch, prebump, and postbump.

Contribution Flow

Gotchas & Traps