Getting started

Built With

For shping web app we use:

  • React:
  • Styling:
    • Styled components - helps us to write styles in component way
    • Polished - a lightweight toolset for writing styles in JavaScript
  • Tools:
    • Storybook - the UI development environment
    • Jest - for testing, for now we use it only for snapshot testing
    • Webpack - bundler
    • Babel - javascript compiler
    • ESlint - javascript linter


To get started make sure you have latest versions of git, npm (usually comes with nodejs), nodejs and yarn on your system

Setting up Dev

git clone
cd react-web
yarn install

Dev server

To start dev server run this

yarn start


Build production ready app

yarn build


For presentational components use storybook as your dev envirement.

yarn storybook



Some Git Rules

There are a set of rules to keep in mind:

  • Perform work in a feature branch.
  • Branch out from develop
  • Never push into develop or master branch. Make a Pull Request. (these branches are protected)
  • Update your local develop branch and do a interactive rebase before pushing your feature and making a Pull Request
  • Resolve potential conflicts while rebasing and before making a Pull Request
  • Delete local and remote feature branches after merging.
  • Before making a Pull Request, make sure your feature branch builds successfully and passes all tests (git-hooks and don't have eslint, stylelint, react/browser erros or warnings).

Git Workflow

  • Checkout a new feature/SHP-085 branch
      git checkout -b <branchname>
  • Make Changes

      git add
      git commit -a

    prefer to use git commit -a over -m


    git commit -a will start an editor which lets your separate the subject from the body. More about it in next section.

  • Sync with remote to get changes you’ve missed

      git checkout develop
      git pull


    This will give you a chance to deal with conflicts on your machine while rebasing(later) rather than creating a Pull Request that contains conflicts.

  • Update your feature branch with latest changes from develop by interactive rebase

      git checkout <branchname>
      git rebase -i --autosquash develop


    You can use --autosquash to squash all your commits to a single commit. Nobody wants many commits for a single feature in develop branch read more...

  • If you don’t have conflict skip this step. If you have conflicts, resolve them and continue rebase

      git add <file1> <file2> ...
      git rebase --continue
  • Push your branch. Rebase will change history, so you'll have to use -f to force changes into the remote branch. If someone else is working on your branch, use the less destructive --force-with-lease.

      git push -f


    When you do a rebase, you are changing the history on your feature branch. As a result, Git will reject normal git push. Instead, you'll need to use the -f or --force flag. read more...

  • Make a Pull Request.
  • Pull request will be accepted, merged and close by reviewer.
  • Remove your local feature branch if you're done.

Writing good commit messages

Having a good guideline for creating commits and sticking to it makes working with Git and collaborating with others a lot easier. Here are some rules of thumb (source):

  • Separate the subject from the body with a newline between the two


    Having a body section lets you explain the context that's useful for a code reviewer. if you can link to an associated Jira ticket, GitHub issue, Basecamp to-do, etc. Also most desktop Git clients have clear separation between message line and body in their GUI.

  • Start subject line with task name
  • Limit the subject line to 50 characters
  • Use imperative mood in the subject line
  • Wrap the body at 72 characters
  • Use the body to explain what and why as opposed to how


  • Keep updated as project evolves.
  • Comment your code if it's hard to understand. Try to make it as clear as possible.
  • If there is an open discussion on github or stackoverflow about the code or approach you're using, include the link in your comment,
  • Don't use commenting as an excuse for a bad code. Keep your code clean.
  • Don't use clean code as an excuse to not comment at all.
  • Keep comments relevant as your code evolves.


  • We have dev, qa and prod environments.

  • Load your deployment specific configurations from environment variables and never add them to the codebase as constants. (WIP)


    Use .env files to store your variables. Rename .env.example which serves as a guide.

  • We use a preinstall script that checks node and npm versions (WIP)


    Some dependencies may fail when used by newer versions of node or installation can fail on old one.

  • Docker (WIP)

  • Use local modules(espessialy tools such as webpack) instead of using globally installed modules


    Lets you share your tooling with your colleague instead of expecting them to have it on their systems.


  • Before using a package, check its GitHub. Look for the number of open issues, daily downloads and number of contributors as well as the date the package was last updated.

  • If less known dependency is needed, discuss it with the team before using it.

  • Keep track of your currently available packages and bundle size: e.g., npm ls --depth=0, bundlesize.
  • See if any of your packages have become unused or irrelevant: depcheck.


    The is a potential risk that you import this unused library in your bundle and ship it for production and as the result increase your bundle size. Find them, get rid of them.

  • Check download statistics to see if the dependency is heavily used by the community: npm-stat.


    More usage mostly means more contributors, which usually means better maintenance which results in bugs get discovered and fixed way quicker.

  • Check to see if the dependency has a good, mature version release frequency with a large number of maintainers: e.g., npm view async. read more...


    Having loads of contributors wont be as effective, if maintainers dont merge those fixes and patches quickly enough.

  • Always make sure your app works with the latest versions of dependencies without breaking: npm outdated.

  • Check to see if the package has known security vulnerabilities with, e.g., Snyk.

  • Make sure all team members gets the exact same dependencies as you


    Use yarn to lock your deps. For now we prefer yarn over npm@5


Write testable code, avoid side effects, extract side effects, write pure functions

Catalogue of components

We use storybook to develop components in isolation from main app to improve component reuse, testability, development speed and create documentation for components at the same time.

yarn storybook

Structure and Naming

  • We organize our files around product features / pages / components, not roles.
├── components
|   ├── PresentationalComponent
|   |   ├── index.js <- your component's code including its styles (styled components)
|   |   ├── index.test.js <- your tests
|   |   └── index.stories.js <- here you keep you storybook story
├── containers
|   ├── Container
|   |   ├── index.js <- your container's code
  • Use PascalCase' 'camelCase for filenames and directory names, css class names. Use PascalCase only for Components.

  • Use index.js to hide implementation details

  • (Recommended) Use component creation tool

Code style

  • Use ESLint and Stylelint to enforce code style.

  • Use .eslintignore to exclude file or folders from code style check.


    You don't have to pollute your code with eslint-disable comments whenever you need to exclude couple of files from style checking.

  • Remove any of your eslint disable comments before making a Pull Request.


    It's normal to disable style check while working on a code block to focus more on the logic. Just remember to remove those eslint-disable comments and follow the rules.

  • Depending on the size of the task use //TODO: comments or open a ticket.


    So then you can remind yourself and others about a small task (like refactoring a function, or updating a comment).

  • Always comment and keep them relevant as code changes. Remove commented blocks of code.


    Your code should be as readable as possible, you should get rid of anything distraction. If you refactored a function, don't just comment out the old one, remove it.

  • Write testable code, avoid side effect, extract side effects, write pure functions.

  • Make your names search-able with meaningful distinctions avoid shortened names. For functions Use long, descriptive names. A function name should be a verb or a verb phrase, and it needs to communicate its intention.


    It makes it more natural to read the source code.

  • Organize your functions in a file according to the step-down rule. Higher`` level functions should be on top and lower levels below.


    It makes it more natural to read the source code.


Add all new strings to src/intl/locales/[en,ru,zh].json files.

And use them like this

import intl from 'react-intl-universal'

intl.get('', { helloWorld: "Hello World!" }) // string - "String with variable {helloWorld}"
intl.getHTML('') // string - "Hi press this <a href=\"/test\">link</a>."

Remember to create fallback strings, just merge ru,zh locales with en locale.

You can use jq util for this

jq -s '.[0] * .[1]' file1 file2

To create xlsx file for translator use intl-utils/importToXlsx.js script.

mkdir builds
node intl-utils/importToXlsx.js ./locales/en.json ./locales/ru.json ./locales/zh.json

To parse xlsx and get json files from translator use intl-utils/exportFromXlsx.js script.

mkdir builds
node intl-utils/exportFromXlsx.js ./new-intl.xlsx

Must read/watch

results matching ""

    No results matching ""