Skip to content

Latest commit

 

History

History
132 lines (85 loc) · 7.75 KB

README.md

File metadata and controls

132 lines (85 loc) · 7.75 KB
Raw

Welcome to the REA client application. This project uses ZenHub to manage our workflow, please install it and navigate to 'Boards' to see what is being developed currently.

Note that many issues are logged only for gathering future requirements and exist as placeholders. These are placed into the ZenHub 'icebox' for later analysis and development and should not be seen as active work items.

Getting started

Here are the things you'll need to run this project and details on how to configure them.

Nodejs

The latest release of node at time of writing is 7.7.2. You should be able to run with any other 7.x version, but this is untested; some tools depend on particular node versions.

The best way to install node for development is to install NVM and then run nvm install 7.7.2. This allows you to easily run different node versions for different projects. If you use NVM, you may also wish to add this to your .bashrc, which will ensure your node version is synced with any projects which define an .nvmrc file:

cd () { builtin cd "$@" && chNodeVersion; }
pushd () { builtin pushd "$@" && chNodeVersion; }
popd () { builtin popd "$@" && chNodeVersion; }
chNodeVersion() {
    if [ -f ".nvmrc" ] ; then
        nvm use;
    fi
}
chNodeVersion;

Note that any commands installed via NPM or Yarn will only be available if you are using the same node version as was active at install time.

Package Manager

We strongly recommend you use Yarn to manage your module packages - it does the same things as NPM but is much faster. Contrary to the install instructions, the easiest way to install is via NPM: npm i -g yarn. Note however the following caveats:

  • If installed via NPM then Yarn is only available for the node version it was installed in.
  • Current versions of Yarn (0.17.x - 0.21.3) install global modules to their own location which does not play nicely with NVM. Use npm i -g instead of yarn global add for installing global packages, but feel free to use Yarn for all other package-related tasks.

Development tools

  • The Redux Devtools Extension is a must-have for time-travel debugging and inspection of app state changes.
  • The Redux dispatch CLI is a nice way of firing actions to the dispatcher for testing your app: npm i -g redux-dispatch-cli
  • The Arc generator can be used to initialise common components. To access the commands npm i -g yo generator-arc:
    • yo arc:component generates new React components for you
    • yo arc:container generates container React components ("higher-order components") for you
    • yo arc:store generates new Redux data stores for you

Linting

Linters are basically a requirement for writing 'good' JavaScript code, since there are so many 'bad' ways to do it. This will also keep your code style aligned with other contributors.

1. Install eslint & flow. You will need at least eslint_d 4.2.4, eslint 3.18.0, flow 0.42.0 & flow-typed 2.0.0.

npm i -g eslint_d eslint flow-bin flow-typed

2. Setup your editor.

Sublime Text 3:

  • Install Package Control if you haven't already
  • Install SublimeLinter
  • Also install the packages SublimeLinter-contrib-eslint_d and SublimeLinter-contrib-flow
  • Check your linter settings (Preferences > Package Settings > SublimeLinter > Settings [User]). Ensure your linters are enabled under user.linters and that your node paths are set correctly under user.paths. Note that the global node packages must be installed in the same node version as you specify here.
  • Use the command SublimeLinter: Enable Debug Mode and bring up the ST console (CTRL/CMD + ~) if you need more help!

Other editors

Please add instructions here!

FlowType

FlowType is a static type analysis layer built to run on top of JavaScript. It is very similar to Typescript, but not as strict- it is designed for iteratively adding static analysis to your projects, rather than forcing you to use it from the start. The syntax is basically the same- more on the official site. In brief:

function square(n: number /* argument type-hinting */): number /* return type hinting */ {
  return n * n;
}

These type annotations are parsed and checked before compiling and then stripped with Babel before running the code- that's about it! You may need to find a colour scheme for your editor that plays nicely with it, but in my experience ES6/JSX-compatible syntax mappings usually work fine.

If you have added new third-party packages and need type definitions for them, you can try running flow-typed install to see if full typings for those packages can be auto-installed for you. This command runs automatically after finishing an standard NPM install command, as configured in package.json.

Setting up the codebase

Now that you have all the prerequisites ready, you can setup the project. Clone this repo, then:

  • Run yarn to install all dependencies

Running locally for development

  • npm run dev to spin up a development server

Recommended editor plugins

Environment variables

The app accepts the following env vars to control its behaviour:

  • NODE_ENV: as usual, set to production to run a non-debug build, omit to use debug mode or set to test when running tests.
  • IP and PORT specify the interface and port to listen on. Defaults to 0.0.0.0:3000. If running in development, the webpack-dev-server will be run on (port + 1).
  • API_URL: sets the base path to the OCP API. If not provided will default to http://localhost:8000/api for connecting to a local instance.
  • PUBLIC_PATH sets the base URL to the website. If not provided, will default to /.

Frameworks & conventions used

  • UI architecture based on Atomic Design principles.
  • CSS is written with modern W3C css and processed via PostCSS plugins. See http://cssnext.io/features/
    • Caveat: local files must be imported with double quotes! Otherwise, postcss-import won't combine them correctly.
  • Built with pure view components (src/components) bound to Redux by way of higher-order components (src/containers). Essentially the design goal is enforcing one-way dataflow and separation of concerns, this is done by writing the UI as simple functional transforms of props data (pure view components) which bind to a single application state (in Redux) by way of accessor functions which pull the data out (higher-order components). All data going back in is sent through Redux's reducers by way of firing a Redux action.