@madgex/fert
v4.1.0
Published
Tool to help build the V6 branding
Downloads
63
Maintainers
Keywords
Readme
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
andpublic/tokens
directories and either refresh the browser page or build a new set of tokens respectively.
Configuration
There are three required files in the root of the branding repo:
brand.json
[required] – a JSON file 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...
}
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) |
| 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']
|
| assumeSite
| Which site we want to display, jobseeker site or recruiter site. Values are either js
or rs
. |
The entry
will be used by Vite to create production bundles.
e.g.
module.exports = {
clientPropertyId: 'ff6102ff-0f4b-43d1-a2c7-83b835b8dee5',
entry: './src/index.js',
assumeSite: 'js',
};
jenkinsfile
- A jenkins file 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.
CLI commands
The CLI will support 3 main commands: dev server (default command), scaffolding a new project and building production assets.
Dev server
fert
Start the Fert dev server in the current directory.
Usage
fert [root]
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 | |
| ----------------------- | ------------------------------------------------------ |
| --template <template>
| Specify the template you wish to use when scaffolding |
| --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
fert build
Process CSS/JS assets specified in fert.config.js
and copy static assets, including templates for distribution.
Usage
fert build [root] --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
fert publish
Usage
fert publish [root] --target [target]
| Option | |
| ---------- | ---------------------------------------------------------------------------- |
| --target
| Where to publish the dist
directory assets.dev
| prod
(string
) |
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.
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
It's intended that the branding repos have their own build/deploy pipeline. Each change that's merged to master
will trigger a build (npm run build
as a common entry point) and the resulting output directory (dist
) is pushed up to the asset-store-api
for use in production.
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
}
}
Its expected that a Jenkins pipeline will run fert publish
to send all built assets to the Asset Store API.
.