humblebee-frontend

This boilerplate is the central point of Humblebee's web projects. It's a living project and therefore it is encouraged that everyone at Humblebee add requests or additional features as they are needed. It's meant to standardize a stack and working procedure, but is not necessarily the full extent of any given project. As a boilerplate it should lay the bar (preferably, lay it high) and be useful in most common use cases.

Prerequisites

• Node (includes NPM and NPX) version 10+
• Yarn version 1.9.4 or later
• Make sure you are logged in to NPM in your Command Line Interface (CLI) by running npm login first; otherwise you may not be able to fetch the Humblebee package

Features

• Built from the ground up to support Progressive Web Apps
• "It just works": Ready to deploy immediately (after installation, of course) since we have everything in place from HTML to UI
• Super performant: Bundling, loading, tree-shaking, code splitting via Webpack
• Asynchronous loading of routes and components
• UI-friendly: Design Tokens make for a central location of all design variables, and React Storybook makes UI development quick and painless
• Extensible configurations, where most of it is hidden out of sight
• High Quality: Enforced linting during devtime as well as pre-commit
• High Standards: Uses a conventional, highly modular structure with options to use Typescript and Jest
• High Security: Uses Snyk to check for project vulnerabilities, and includes A+ grade server headers with prebaked Content Security Policy

Stack

• Webpack 4
• React 16.8
• React Storybook
• Styled Components 4
• Babel 7
• ESLint, Stylelint, TSLint
• Prettier
• Jest (optional)
• Typescript 3 (optional)
• Figmagic

Installation

Installation is ONLY done via @humblebee/humblebee-starter.

Run yarn setup to install all of the things. Running only Yarn means you will only get the dependencies, but no setup for Storybook etc.

Also: Make sure to update manifest.webmanifest, index.html and other client-facing locations to have the pertinent, correct information for your project.

Commands

All commands are, as usual, available in package.json. Make sure to configure the various variables, such as URLs before doing anything.

• yarn commands: Display ALL available commands
• yarn dev: Start development server
• yarn build: Output a static build
• yarn plop function: Create new function with Plop (function file, test)
• yarn plop class: Create new class with Plop (class file, test)
• yarn plop component: Create new component with Plop (component file, Styled Components file, Storybook item)
• yarn storybook: Start React Storybook
• yarn build:storybook: Build React Storybook
• yarn teardown: Take down Surge site
• yarn figmagic: Grab everything from your linked Figma design document (specs, images, tokens)
• yarn figmagic:tokens: Get tokens (and build them) from your linked Figma design document

Test commands: those ones currently require the app itself to run in another process (launch yarn dev in another process before).

• yarn test:e2e: Run end-to-end tests (using puppeteer: automatically open a window, start clicking around, filling forms etc.)
• yarn test:visual: Run visual regression tests: will take screenshots of pages, and compare them with previous version.
• yarn test:all: Run end-to-end and visual regression tests (feel free to adapt it to run any kind of test you wish!)

PWA considerations and asset generation

Splash screens

The folder src/assets/splash contains the various sized screens that a PWA requires (at least on iOS) when starting in standalone mode. They are not unused unless you specify standalone as the display mode in webmanifest.manifest.

Image optimization

The postbuild process will optimize all SVGs, and Webpack will treat any JPGs.

For manual SVG optimization, please use SVGO or SVGOMG. All settings should be activated except "Remove XMLNS" and "Remove viewbox" — We want the viewbox rather than pixel values. Precision can usually be set really low, and often it works just fine to put it to the lowest value (1).

Icons/favicons

Create a high-resolution icon of at least 512x512px, then convert it with the following two sites:

• https://realfavicongenerator.net
• https://app-manifest.firebaseapp.com

These generators create a bit different filesets. What you want is to get all of the files of the two ZIP files, except the manifest file which we have already set up correctly. These (fav)icons should go into the folder src/icons/.

Creating components

Rather than manually create components, use yarn plop to do so. It will create a main component file, Styled Components file, test and a Storybook item for you.

State management and connected components

We use React's context and provider pattern for state management, or just plain-vanilla prop passing.

Figmagic API keys and URL

Make sure these are correct both in package.json, node_modules/figmagic/bin/getImages.mjs and node_modules/figmagic/bin/meta/keys.mjs.