Frontend Practices

File and Folder Structure

The UI is served up by the Rails application using eRuby HTML templates (in the app/views folder), which in turn contains <script> tags that load up JavaScript bundles. There are two main JavaScript codebases:

1. Rails JavaScript in app/assets/javascripts, which the app is mostly written in, uses jQuery, and is no longer considered the latest best practice for web applications. We plan to move away from this codebase in favor of a React single-page application. These files end in .js.
2. React JavaScript in client/app/bundles is written in React and Flow, is currently a work in progress. Part of this new codebase is also revamping the UI/UX design of the application. React component files end in .jsx and regular JavaScript files end in .js.

Code Quality

• We use 2 space indentation.
• We use camelcase for JS and SCSS files.
• We use single quotes for JS and SCSS files.
• We follow Airbnb's JavaScript style guide.

JSHint for Rails JavaScript

bundle exec rake jshint

Note that there are currently a lot of JSHint errors, so do not expect to run JSHint and have it pass without errors. However, it may prove useful for highlighting errors in the file you are working on. You can read about JSHint here.

Linting for React JavaScript

Running yarn lint in the client directory will run ESLint, Prettier, and Flow.

ESLint for React JavaScript

cd client
yarn lint:eslint

You can read about ESLint here.

Prettier for React JavaScript

cd client
yarn lint:prettier

You can read about Prettier here.

Flow for React JavaScript

We use Flow to be able to annotate types in JavaScript (since JavaScript is inherently an untyped language). You can read about Flow here.

To run flow checks:

cd client
yarn lint:flow

Types

Some NPM packages have Flow type enabled but fail the Flow checks (e.g. radium) because it relies on an older Flow version compared to the main project. You'll want to put the package path under the [ignore] section of client/.flowconfig, for example:

[ignore]
.*/node_modules/radium/.*

If you're wondering why we don't just ignore the entire node_modules folder, it's because some NPM Packages do have correct type definitions, and we don't want to ignore those.

Development Environment

Storybook

For the React JavaScript codebase, we use Storybook for interactive development and testing of the React UI components. To start this environment:

cd client
yarn && yarn storybook

Once you start it, type the localhost address in your browser indicated by the terminal. You can develop your React components in here by creating a *.stories.jsx file inside the client/app/stories folder. Look at the other existing stories as inspiration.

Technical Design Considerations

Internationalization and Localization (i18n and l10n)

In order for UI components to be reusable across multiple languages and locales, you will want to be able to pass-in text that could be written in any language. For example, creating an OK button:

Not i18n-friendly

export default class OkButton extends React.Component<any> {
  render() {
    return <button {...this.props}>OK</button>;
  }
}

// The JSX would be used like this
<OkButton />

i18n-friendly

export default class OkButton extends React.Component<any> {
  render() {
    const { text, ...props } = this.props;
    return <button {...props}>{text}</button>;
  }
}

// The JSX would be used like this
<OkButton text={localeBundle.OK} />

Automated Testing

Please see our Automated Testing document, specifically the frontend document.