FERT - Front-end Rollout Tool

@madgex/fert is the CLI used to build Madgex branding repositories for Jobseeker and Recruiter Services.

Each clients job board has its own Git repo (madgex-<CPID>) for that site's branding and settings — which header/footer theme, Design System Tokens, assets and V6 config — FERT is your tooling to work with this.

Requires Node.js 22.17 or newer.

Why FERT Exists

Madgex runs many client job boards on the same platform. In V6, each request is scoped by CPID, so client-specific branding and configuration must live outside shared application code. A branding repo is that boundary: one CPID, one source of truth for the client-facing presentation and V6 config.

FERT exists to make that model practical. It gives delivery teams a local preview that behaves like the platform, validates common mistakes before deployment, builds the static assets V5 and V6 consume, and publishes those assets through the shared Jenkins pipeline.

This matters during the V5 to V6 migration. Some traffic is still served by V5, while V6 is a shared SaaS frontend. Headers, footers, assets, and configs need to work across both worlds without creating one-off client code or bespoke deployment steps.

Useful Docs

More detailed branding guidance lives in docs/:

| Doc | Use it for | | ---------------------------------------------------------------- | ----------------------------------------------------------------------- | | Building Frontend Branding | End-to-end branding workflow, themes, configs, translations, deployment | | Branding Repository Overview | Required repo structure and service file layout | | Checklist | Pre-merge checks for branding work | | Glossary | CPID, affiliate, service names, and platform language | | FAQ | Common branding questions |

Common external references:

• Header/footer theme Storybook
• Design system base tokens
• V6 redirects guide

Quick Start

Find your CPID in Madgexverse. Repo: madgex-<CPID>.

| Situation | Docs | | --- | --- | | New or existing repo setup | Getting started | | Layout, config files, services | Branding repository overview | | Themes, tokens, configs, deployment | Building frontend branding |

npm install && npm run dev

To run one service at a time: npx fert --service-name=jobseekers-frontend or cd services/jobseekers-frontend && npx fert.

Configuration

Root fert.config.js (CPID) and per-service fert.service.config.js are required. Optional externalAssets loads third-party CSS/JS (for example Adobe Fonts).

See Branding repository overview for structure, examples, and package.json scripts.

Commands

Run commands from the branding repo root, from a service folder, or with --service-name.

fert / fert dev

Starts the local layout server and Vite dev server.

npx fert
npx fert --service-name=jobseekers-frontend
npx fert --open --port 4001

On startup, FERT validates the service, validates root config/*.json (non-blocking warnings), builds tokens from brand.json, and watches those files plus templates for reload.

Options:

| Option | Description | | ----------------------- | ------------------------------------------------------- | | --open | Open the browser | | --host [host] | Use a specific host | | --port <port> | Use a specific port; FERT moves to another port if busy | | --service-name <name> | Run one service |

fert validate

Runs service validators for every service without building:

npx fert validate

Validators cover service config, brand.json, translations, redirects, required assets, CSS constraints, and nav links. Root config/*.json files are validated during fert dev and fert build, not by fert validate.

fert build

Builds design tokens and assets. Style Dictionary, via @madgex/design-system, transforms brand.json into CSS custom properties and JSON token output under public/tokens/; Vite then builds the service assets into dist/.

CI runs this inside shared/Dockerfile.brandingRepoPublish as npm run build --target=${ENVIRONMENT}.

npx fert build --target=dev
npx fert build --target=production
npx fert build --target=production --only=tokens
npx fert build --target=production --only=assets

--target is required and must be dev or production.

fert publish

Uploads an existing dist/ folder to the Asset Store API. Run fert build first when publishing manually.

⚠️ [Warning]

This is a deployment command. Without --dry-run, it uploads assets to the selected environment and sends CloudFront invalidations. Be especially careful with --target=production.

npx fert build --target=production
npx fert publish --target=production
npx fert publish --target=dev --dry-run

--target is required (dev or production). prod is also accepted and maps to production.

fert configs

Queries, downloads, or publishes V6 config JSON from root config/.

⚠️ [Warning]

--publish production updates production config and, by default, deletes remote keys missing locally so the API matches the repo. Use --skip-key-delete only when you intentionally want to avoid that parity check.

npx fert configs --query
npx fert configs --query JobBoardConfig.jobboardCustomRoutes
npx fert configs --download production
npx fert configs --publish production
npx fert configs --publish production --skip-key-delete

fert init [root]

Scaffolds a branding repo from repo-template/.

npx @madgex/fert init .
npx @madgex/fert init . --cpid ff6102ff-0f4b-43d1-a2c7-83b835b8dee5

fert init-template

Copies a header/footer theme into a service so it can be edited as a custom template:

npx fert init-template

This is not part of the default workflow. Start with a theme macro from Storybook and only use this when a custom template has been agreed.

Global Options

| Option | Description | | ----------------------- | ------------------- | | --service-name <name> | Run one service | | --no-cache | Disable local cache | | --purge-cache | Clear local caches | | -h, --help | Show help | | -v, --version | Show version |

CI/CD

Every push to a branding repo is picked up by Jenkins on nomad.

The shared Jenkins pipeline (via each repo's jenkinsfile) runs:

1. npm run build --target=${ENVIRONMENT} using shared/Dockerfile.brandingRepoPublish (Node 24 in CI).
2. fert publish --target=${ENVIRONMENT} to upload built assets.
3. fert configs --publish ${ENVIRONMENT} to apply root config/*.json.

| Branch | Asset target | Config API target | Used by | | ---------------- | ------------ | ----------------- | ----------------------------- | | master | production | production | V6, V5 Staging, V5 Production | | Any other branch | dev | dev | V5 Local Dev, QA, UAT |

Pushing to master deploys to production automatically. Manual runs of fert publish --target=production or fert configs --publish production should be treated as production changes, not local verification. Prefer branch builds for dev/UAT checks and use --dry-run when testing upload behaviour locally.

Builds usually complete quickly, but Jenkins multibranch scanning can take a few minutes. See the deployment docs for rollout scenarios and V5/V6 notes.

How FERT Works

• Hapi runs the local preview server.
• header-footer-podlet provides the header/footer themes as Nunjucks macros and renders header.njk / footer.njk.
• Vite handles local HMR and production asset bundling.
• @madgex/design-system provides the base tokens that brand.json overrides.
• Style Dictionary transforms those design tokens into CSS custom properties and JSON output in public/tokens/.
• @madgex/config-api-sdk validates and publishes V6 config files.
• chokidar watches files and triggers rebuilds during local development.

Developing FERT

Use this section when changing this CLI, rather than using FERT inside a branding repo.

Install and check the package:

npm install
npm test
npm run lint

Link this checkout into a real branding repo:

cd ~/Repos/madgex-frontend-rollout-tool
npm link

cd ~/Repos/madgex-<CPID>
npm link @madgex/fert

Then run the branding repo as normal:

npm run dev
npx fert validate
npx fert build --target=production
npx fert publish --target=dev --dry-run

You can also run the CLI directly:

node ~/Repos/madgex-frontend-rollout-tool/bin/cli.js dev

To debug, open this repo in VS Code, set breakpoints, open a JavaScript Debug Terminal, cd to a branding repo, and run a fert command.

To go back to the published package:

cd ~/Repos/madgex-<CPID>
npm unlink @madgex/fert
npm install

cd ~/Repos/madgex-frontend-rollout-tool
npm unlink

Repository Map

| Path | Purpose | | ------------------------------------- | ------------------------------------ | | bin/cli.js | CLI entry point | | bin/commands/ | Command implementations | | bin/validators/ | Branding repo validators | | server/ | Local Hapi preview server | | repo-template/ | Files copied by fert init | | docs/ | Branding developer docs | | shared/ | Shared Dockerfile for Jenkins builds |

License

UNLICENSED - internal Madgex/Wiley use only.