@rush-partners/fs-ui-components

Project: FS UI Components

This repository contains the building blocks for all our websites, applications and plugins.

It is a component Library built with Reacthttps://reactjs.org/ and showcased in a tool called Storybook.

For a quick example of the power of Storybook please visit: Wix Storybook and the corresponding GitHub source

Start

We use Storybook to create a simple environment

• git clone [e-mail]:fantasydevelopment/fs-ui-components.git
• git checkout develop
• npm install
• npm run dev:start

Usage

To use this component library in other apps it should be as easy as the below

• npm install --save @rush-partners/fs-ui-components
• import { Button } from '@rush-partners/fs-ui-components'

Node / NVM

We will utilise node version 8.10.4, the best way to manage node is through NVM.

List all NVM node versions

• nvm ls-remote

Install

• nvm install 8.10.0
• nvm use node 8.10.0

Update NPM - 5.7.1 at time of writing

• npm install npm@latest -g

Building the components (WIP)

This is work in progress currently we are using the components directly with NPM Link - but we should be utilising the built assets.

To use the components in an app we use the files created inside the dist folder These are build using the folowing command

• npm run prod:build

This uses Babel to create the JS and a webpack configuration to process the assets. The dist folder ignores the specs and stories

Definition of Done

Outline what is required for the Git Process to be achieved.

• Brower compat
• Tests
• Stories

GIT Process

We will run a simplified feature branch process, there are shorter methods to achieve the following routines but below is recommended to avoid git issues.

Please Read also Git Merge and Branch

• When a Trello card is assigned, you will branch a feature from develop
  • Naming of this branch should be inline with the Trello ticket
    • git checkout -b feature
• Develop on your branch
  • Try to keep only one branch active
  • Publish your branch immediately so others know you are working on this
  • Commit regularly locally on each small achievement
    • git commit -am "Creative message on the additions"
  • Push to remote when a section is done
  • Commit and Push every evening when you finish for the day
  • Make sure you git pull in the morning
  • This will only pull the branch you have active.
  • Someone else may have worked on the branch also!
  • When pulled do an npm install to install new dependancies
• When the feature is complete merge develop into your feature branch
  • git checkout develop
  • git pull
  • git checkout feature
  • git merge develop
  • Fix conflicts and write merge message
  • npm install to make sure packages are up to date
  • Run lint and test, this is also done on pre-push automatically
  • npm run prod:test
  • Fix issues
• Maybe need to add files
  • git add .
• Commit
  • git commit -am "Creative message on the additions"
• Push
  • git push

So now you have your feature branch on BitBucket in state you are happy for merging into Develop

• Browse to Bitbucket to create a pull request
  • https://bitbucket.org/fantasydevelopment/fs-ui-components/pull-requests/new
  • Follow the instructions, select your branch on the left and develop on the right
  • Title and Description
  • Ian Warner is the default reviewer for this project, please add specific others
  • Selecting to Close the branch will effectively delete it
• Once the PR is created the reviewer will be alerted
  • Code review should be quick if the PRs are kept small
  • Pester the reviewer on Slack to Merge ASAP so it does not become stale
  • Comments and tasks may be created for the PR these should be reolved as a priority
  • If edits need to happen then repeat the cycle above, but use the same feature branch
• On passing review the branch will be merged into develop
  • Feature branch deletion needs to be checked - the close checklist
  • Or reviewer should delete the branch after a certain amount of time

Closing/Deleting a Branch

On bitbucket when actioning a pull request you can choose to close branch which apparently deletes it, doing the below will save some reference. Use -d flag which only deletes if the branch has been merged upstream

• git tag closed-footer-organism-component footer-organism-component
• git branch -d footer-organism-component
• git push -d origin footer-organism-component
• git fetch --all --prune
• git branch -a

Base a branch of a tag

git checkout -b new-feature closed-footer-organism-component

JavaScript Code Style

We utilise the default StandardJS for Javascript style and linting. The rules can be viewed here

Please make sure you set up your IDE to conform with StandardJS.

The settings for VS Code are as follows:

"javascript.validate.enable": false,
"standard.autoFixOnSave": true,
"standard.usePackageJson": true,
"standard.options": {
    "globals": ["it","test", "expect", "describe"],
    "parser": "babel-eslint"
}

It is recommended to use VS Code for front-end development as we will be creating our own snippets and hooks.

SCSS / Less / CSS Code Style

We utilise Stylint for CSS style and linting. The rules can be viewed here

There are in addition several plugins we use for the type of code we create.

The standard config is used

Working Locally on an NPM

You do not always want to publish an NPM to get a small change happening in another project, so to work locally we use symlinks. NPM comes with this built in.

In the component library run

• npm link
• https://docs.npmjs.com/cli/link

Take note of the name - in our case @rush-partners/fs-ui-components

In the package you want the npm to be linked to run

• npm link @rush-partners/fs-ui-components

If you happen to run npm install in the project you will need to re-run the above command again to re-link the project. Should add an alias to automatically create this association.

Ignore for now:

If you make changes locally in the components then you will need to build these for use in the project apps.

• npm run prod:build

Publishing the NPM

This should only be done by David or Ian

Any files with a package.json file can be published on NPM

You can test your local user with

• npm config ls

Versioining is an critical point of using NPM, update the version with the following commands, this will also create a tag in GIT. We will employ semantic versioning (semver) https://docs.npmjs.com/getting-started/semantic-versioning so choose the command that relates to the bump.

• npm version patch
• npm version minor
• npm version major

To push the tags use

• git push --follow-tags

Login to NPM, run the command below and enter the user and pass

• npm login

Org scoping, this should already be set up but documenting

• npm config set scope rush-partners --global

To publish use in the directory root with a package.json

• npm publish

Remove package

• npm unpublish --force

File system

All files and directories should have the following permissions. This may be important when copying over from a USB backup where permissions can be changed and then effect GIT commits.

• Files 0644 or rw- r-- r--
• Directories 0755 or rwx r-x r-x

To implement these run the following commands on the parent directory.

• find [FULL_PATH] -type f -exec chmod 644 {} \+
• find [FULL_PATH] -type d -exec chmod 755 {} \+

Husky

We use husky and commit runtimes to automatically lint and test the codebase before the developer pushes to the codebase.

• https://github.com/typicode/husky

Testing

Jest is our testing framework of choice: https://facebook.github.io/jest/ We will check out Enzyme also: https://github.com/airbnb/enzyme

As we are using Babel then please follow the setup for babel-jest

• npm install --save-dev babel-jest babel-core regenerator-runtime

https://facebook.github.io/jest/docs/en/snapshot-testing.html

Linting

Assuming you are using VSCode this repo is set up to use standardJS and Stylelint.

More information to be added on the extensions to install for VSCode

Theming

Semantic UI React theme

https://github.com/Semantic-Org/Semantic-UI-LESS

example of available button variables

https://github.com/Semantic-Org/Semantic-UI-LESS/blob/master/themes/default/elements/button.variables

More work needs to be done around the theming overrides and ease of include semantic.

Storybook: https://storybook.js.org

We will use Storybook for Visual and Automated testing of our compontent library. Please read the following resources

• https://storybook.js.org/basics/guide-react/

The following addons are included

• Actions: https://github.com/storybooks/storybook/tree/master/addons/actions
• Deployer: https://github.com/storybooks/storybook-deployer
• Info: https://github.com/storybooks/storybook/tree/master/addons/info
• Knobs: https://github.com/storybooks/storybook/tree/master/addons/knobs
• Notes: https://github.com/storybooks/storybook/tree/master/addons/notes
• Options: https://github.com/storybooks/storybook/tree/master/addons/options
• ReadMe: https://github.com/tuchk4/storybook-readme
• Specification: https://github.com/mthuret/storybook-addon-specifications

Through the deployer we can publish the storybook to a live URL on GitHub pages, currently testing at.

• https://rushpartners.github.io/fs-ui-components/

Run the deployer with : npm run prod:deploy-storybook

Babel

• https://github.com/babel/babel/tree/master/packages/babel-preset-env

Sketch

https://developer.sketchapp.com/guides/sketchtool/

137 Shirts

At the moment there are issue with the libraries not being installed, so will need to reference directly, or create an alias

CD into the Shirts folder in the FS-UI-Components repo

• cd ~/Documents/r/rush-partners/public/fs-ui-components/shirts

• /Applications/Sketch.app/Contents/Resources/sketchtool/bin/sketchtool export artboards /Users/ianwarner/Downloads/2018-03-02_FB_Shirt Designs_v2.sketch --formats=svg

• npm run prod:shirts

Run the Script to convert the SVGs into React components using SVGr

Sketch CLI (it will ask for your user password)

• N/A has a bug at the moment so just use the above
• sudo sh /Applications/Sketch.app/Contents/Resources/sketchtool/install.sh

svgo --config='{ "plugins": [ { cleanupIDs: { prefix: { toString() { this.counter = this.counter || 0; return id-${this.counter++}; } } } } ] }' *.svg

svgo --enable={cleanupIDs} *.svg

Icons

• cd ~/Downloads

• /Applications/Sketch.app/Contents/Resources/sketchtool/bin/sketchtool export artboards /Users/ianwarner/Downloads/sketch.sketch --formats=svg

• /Applications/Sketch.app/Contents/Resources/sketchtool/bin/sketchtool list pages /Users/ianwarner/Downloads/sketch.sketch

SVGr

Create react components from a series of SVGs such as Icons or Shirts

• svgr -d shirts componet/atom/Shirt/resources/shirts

## Resources

Starter templates

• https://github.com/Metnew/suicrux
• https://github.com/darkredz/react-semantic.ui-starter h

List

• https://github.com/brillout/awesome-react-components

Component scaffolds

• https://github.com/mesosphere/reactjs-components
• https://github.com/hackoregon/component-library
• https://github.com/Tripwire/octagon
• https://github.com/jhudson8/react-semantic-ui

Tools

• https://github.com/styleguidist/react-styleguidist
• https://github.com/JedWatson/generator-react-component
• https://hackernoon.com/writing-clean-and-concise-react-components-by-making-full-use-of-es6-7-features-and-the-container-4ba0473b7b01