npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@madgex/fert

v4.1.0

Published

Tool to help build the V6 branding

Downloads

63

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 and public/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.

.