@madgex/fert

FERT - proposed approach/readme

Madgex brand tooling for anyone.

Front-end Rollout Tool – Tooling to help scaffold, develop and deploy Madgex client branding

Why FERT

The Madgex job board brands all have a custom headers, footers and their associated JavaScript & CSS. In the past we've struggled with finding an easy local development & roll-out setup. Fert is an attempt to address that.

Requirements

• To be a one-stop shop for:

  • Scaffolding a new project
  • A dev server to allow easy brand development
  • Builds distributable assets

• Must be able to install via NPM or internal registry

• Must work cross-platform (Windows and *nix)

A human-first design

To empower & serve its users, we should design this CLI with the users in mind. Ensuring it feels as familiar as possible, following established patterns and is has the following:

• Easy to learn commands from a inbuilt help screen

• Easy to read/understand error messages

• Empathy in the error messages – can some helpful context be provided with the error to assist the user remedy the issue?

Under the hood

• Hapi is used for the local dev server

• Vite for HMR, serves the JS entry & bundles assets for production

• Style Dictionary is used to transform Design Tokens into various outputs, inc. JSON, CSS Custom Properties and SCSS variables. The output is built into public/tokens/

• Chokidar is used to watch for changes in the templates and public/tokens directories and either refresh the browser page or build a new set of tokens respectively.

Configuration

There are two required files in the root of the branding repo, and two required files in the service folder:

/fert.config.js [required] – a configuration file in the root of the branding repo specifying the following config to both the Fert dev server and the production asset build:

Option
clientPropertyId	The clientPropertyId associated with the branding repo (required)

e.g.

module.exports = {
  clientPropertyId: 'ff6102ff-0f4b-43d1-a2c7-83b835b8dee5',
};

/jenkinsfile - A jenkins file in the root of the repo containing the pipeline which will build and send the assets to S3. Every push to the repo will trigger a jenkins build automatically. Changes on master will trigger a build and send assets to the production bucket. Any other branches will send the assets to the jb.dev bucket.

/services/<service-folder>/brand.json [required] – a JSON file in a service folder that supplies the base branding tokens. These values will be merged with the Design System tokens & a full set of branding tokens will be created. see here for format

e.g.

{
  "color": {
    "brand": {
      "1": {
        "base": { "value": "#005689" }
      }
    }
  }
  // more branding tokens applied here...
}

/services/<service-folder>/fert.service.config.js [required] – a service configuration file in the service folder, specifying the following config to both the Fert dev server and the production asset build:

Option
serviceName	Which service to display and deploy, e.g. jobseekers-frontend, recruiterservices-frontend.
entry	The JavaScript entry file. Any assets (CSS/SCSS/SVGs) included will be processed and be part of the output. Defaults to ['src/index.js']
externalAssets

The entry will be used by Vite to create production bundles.

e.g.

module.exports = {
  serviceName: 'jobseekers-frontend',
  entry: './src/index.js',
  externalAssets: {
    links: [],
    scripts: [],
  },
};

CLI commands

The CLI will support 3 main commands: dev server (default command), scaffolding a new project and building production assets.

• Dev server

• Scaffold

• Build

• Publish

Dev server

Start the Fert dev server for 1 or all services: fert | fert --service-name=jobseekers-frontend

Start the Fert dev server for 1 service from the service folder: cd services/jobseekers-frontend fert

Usage

fert

Outline of implementation

A fast, minimal development server that allows the developer to see the header/footer templates and branding (Design System tokens) specified in the local repo applied to a Design System-based HTML page.

The server will be a hapi server, importing the header/footer micro front-end server(s) as dependencies, running all together to render the page.

Changes to the local tokens will cause the DS tokens to be rebuilt.

Changes to the local fert.config.js will be reflected in the dev servers environment.

Changes to any local file will be reflected in the developers browser without having to manually refresh.

Scaffold

fert init

When faced with an empty branding repo, this will help the user get started with the boilerplate branding project template

Usage

fert init [root]

Options

Option
--cpid <cpid>	Specify the clientPropertyId to use in the new project

Outline of implementation

The init command will clone a well-maintained boilerplate repo into the target directory. It may be good to use a tool like degit for faster cloning & not confusing git with nested, hidden .git directories.

The --force option would destructively reset the branding repo to a common baseline, resetting the content.

The source boilerplate repo: https://github.com/wiley/madgex-00000000-0000-0000-0000-000000000000 The init command is intended for an automation tool which will create a new branding repo, run this command and commit the new files.

Build

Process CSS/JS assets specified in fert.config.js and copy static assets, including templates for distribution.

Run for all or a specific service fert build | fert build --service-name=jobseekers-frontend

Run for 1 service from the service folder: cd services/jobseekers-frontend fert build

Usage

fert build --only [tokens | assets]

Option
--only [task]	Specify a single part of the build process to run (string | tokens | assets)
--config <path>	Override the internal default Vite config & provide a custom vite.config.js file to use to build assets.

Outline of implementation

Using Vite, the entry in the fert.config.js file is processed and bundled to the dist directory.

Templates are copied to dist.

Public assets are copied to dist.

The resulting dist directory is uploaded wholesale to the assets-store-api for use in production.

Templates & CSS may be processed using the CSS Modules system to encapsulate header/footer styles & prevent bleed into the rest of the page.

Publish

From root, run for all services or a specific service: fert publish --target=production | fert publish --target=production --service-name=jobseekers-frontend

Run for 1 service from the service folder: cd services/jobseekers-frontend fert publish

Usage

fert publish --target [target]

Option
--target	Where to publish the dist directory assets. dev | production (string)
--dry-run	Dry run, dont actually upload anything

Send all files and directories created in the dist directory to either development or production versions of the Asset Store API. Files uploaded to the Asset Store API are available via a CloudFront-based CDN.

Outline of implementation

Index all the files and their paths in the dist directory, and using a recursive function upload each item (destructively) to the Asset Store API.

The Asset Store API uses a multi-part form upload to PUT files in the client directory. Upload paths are respected, directories are created on the fly.

Configs

fert configs

A set of commands to help with publishing, downloading & referencing project configs.

Usage

fert configs --[query|download|publish] [env]

Option	Description
--query [configName]	Describe known keys for a config, omit to list all known configs
--download	Download known configs from the Configuration API for environment "dev" or "production"
--publish	Publish configs to Configuration API environment "dev" or "production"

Example usage

Its assumed you're running from a branding repo in all examples

Review all known configs

# fert configs --query

Fert v0.0.0-development

Available config schemas...
 * JobSeekerDesignConfig
 * JobSeekerSiteConfig
 * jsfe-config
 * webconfig
 ...

Review validation schema & default values for a config

# fert configs --query JobBoardConfig.filesizeDefinitions

Fert v0.0.0-development

Getting schema description for config: JobBoardConfig.filesizeDefinitions...
{
  "documents": {
    "type": "number",
    "flags": {
      "description": "The definition in MBs of how large documents can be",
      "default": 1
    }
  }
}

Configs default values:
{
  "documents": 1
}

Download known configs for the current client (specified in fert.config.js) from the Configuration API. This is intended as a one-time command to get the current config values in the repo

# fert configs --download production

Fert v0.0.0-development
✔ Downloading v6 configs...
Saving files...
 - JobBoardConfig.applicationForm.json
 - JobBoardConfig.articlesFilterByDate.json
 - JobBoardConfig.careerpathCountryIso.json
 - JobBoardConfig.careerpathGlobalRoleSettings.json
 ...

Publish all known, valid configs found in branding repos ./config/* for the current client. In this scenario, there is only ./config/jsfe-config.json

# fert configs --publish production

Fert v0.0.0-development
✔ Config validated: jsfe-config
✔ Project configs applied to configuration-api.job.madgexhosting.net
upload

Global options

These options are available no matter the command used.

--no-cache — Do not use the in-built file-based cache. This includes CPID, config & AWS CloudFront Distribution lookup (default: true)

--purge-cache — Purge/clean all local caches.

CI/CD

All branding repos use a common jekinsfile and Dockerfile to build/deploy, and will use this FERT tool.

• Here is the jenkinsfile all branding repos use: https://github.com/wiley/madgex-jenkins-shared-library/blob/master/vars/clientRepoDeploymentPipeline.groovy .
• And the Dockerfile they all use is in this repo.

Each change that's pushed to a branch will trigger:

1. a build (npm run build inside the Dockerfile as a common entry point), which creates a dist folder full of assets ready to upload.
2. The jenkinsfile pipeline will run fert publish to send all built assets to the Asset Store API.
3. The jenkinsfile pipeline will run fert configs --publish, Uploading the branding repo's client /configs to the configuration-api.

[!NOTE] > master branch will go to production. All other branches will go to jb dev. master branch will go to production. All other branches will go to jb dev.

npm scripts

Here are the default npm scripts in a Fert-scaffolded project.

{
  "scripts": {
    "dev": "fert", // start dev server
    "build": "fert build" // build assets for production
  }
}