CaTUstrophy frontend

Frontend part for our catastrophe aid tool.

Setup

We assume you run a reasonable sort of Linux or OS X with node.js 6.x (use nvm!) and npm 3.x.

1. Clone this repo

   git clone https://github.com/caTUstrophy/frontend.git

2. Change into folder

   cd frontend

3. Install packages

   npm i

4. Configure your environment. Start by cloning the example configuration and adapt to your needs.

   cp environment.js.example environment.js

5. (Optional: Fire up the backend)

6. Start development server

   npm start

7. Open spawned website: http://localhost:3000/

Changes you make to the code are applied immediately and hot-loaded. Hit CTRL+H to show/hide the Redux DevTools, CTRL+M to move them around and CTRL+SHIFT+M to switch between the available monitors:

• Inspector
• Slider
• Chart (might require reopening the DevTools to render correctly)

Technology overview

All new code should be written in ES7/JSX. And embrace the ecosystem!

Core technologies

• React (user interface / DOM)
• Redux (predictable state container)
• Material-UI

Implied remarkable packages

• react-redux (bindings)
• react-router (router)
  • react-router-redux (bindings for router)
• redux-devtools (live-editing / time travel)
  • redux-slider-monitor (additional monitor for better time travel)

Tooling

• webpack (module bundling etc.)
• babel (transpiler)
• express (development server)
• obviously relies on node.js / npm

Design

• Follow the material design guidelines
  • See icons
• Use Material-UI's React components where possible
  • style with theming (not CSS) where applicable

CSS

We use Foundation Sites. Write SASS, only. Use their mixins et cetera wherever possible. Don't use prefixes, we have autoprefixer set up (aggressively i.e. > 1%).

We should eventually use extract-text-webpack-plugin to generate a CSS file, but for now it doesn't seem strictly necessary.

Testing

• Write tests for everything.
• Put your tests in test/.
  • Put them in a matching subfolder, replicating the project structure. (E.g. forms located in forms/ are to be tested in test/forms/)
• Start the tests with npm test (calls mocha-webpack --webpack-config webpack.config.js --recursive test internally)
• Configure your IDE to run tests while you develop.

Tooling

• mocha (test framework) via mocha-webpack
• unexpected (assertions)
  • unexpected-react (JSX assertions)
  • sinon (spies) and unexpected-sinon (spy assertions)
• ReactTestUtils (official react testing utilities)
• domino (fast fake DOM)
• Some test/helpers (mostly copied from smaato/react-test-kit)
• Travis runs npm test automatically, current status:

Code coverage

Code coverage is assessed with nyc which is built on top of istanbul. It is monitored and published with coveralls. You can see the current details at coveralls.io or with this fancy badge:

Deploying

Run npm run-script bundle to create a webpack build in dist/. The command internally runs

webpack -p --progress --config webpack.production.config.js

Read webpack.production.config.js for the details.

Currently there is no HTML generated, an index.html should be derived manually.

There are no CSS files for now, it is inlined with the JS sources by webpack.

Resources to familiarize yourself with the technologies

• React tutorial in the official docs
  • the official docs have many guides and tips.
• 30 free videos on Redux, by the creator