Forem: Halla Moore

Structuring a Complex React/Redux Project

Halla Moore — Wed, 07 Mar 2018 17:49:16 +0000

The Nylas engineering team recently updated the Nylas Dashboard, giving everyone on our customer's teams -- from developers to product managers, sales engineers, customer success reps and finance teams -- the ability to access their Nylas API account.

After our blog post about increasing developer speed during the revamp of the Nylas Dashboard, we had some follow-up requests for a) the scaffold script we wrote, which is now available here, and b) the general structure of the project.

Our dashboard front-end code is a React/Redux application, and the general structure looks something like this:

src/
  appConstants/
  components/
    DropdownMenu/
      dropDownArrow.png
      index.js
      index.test.js
      stylesheet.js
    ...
  containers/
  higherOrderComponents/
  layouts/
  models/
  modules/
  screens/
  store/
    accounts/
      actions.js
      constants.js
      endpoints.js
      reducers.js
      selectors.js
    applications/
    ...
    actions.js
    api.js
    configureStore.js
    rootReducer.js
    selectors.js
  index.css
  index.js
  registerServiceWorker.js
  Routes.js

🙀 There’s a lot going on here, so I’ll briefly break down what each directory or file is for.

appConstants/ is simply where we kept any application-wide constants, like API keys for third party services. We originally named this constants/, but it turned out that there was another constants node module elsewhere in the project that caused naming conflicts, so we renamed it to appConstants/ instead.

We broke up our React components into multiple directories to try to keep things grouped in a more manageable manner. We initially only had a split between presentational components and containers. The important distinction between these is that presentational components are stateless while containers are not. You can learn more about the difference between presentational components and containers from this article. However, as we continued to add more and more components, we needed more separation. The directories we ended up with are:

components/ - the original directory for presentational components. Most of our presentational components still live here.
containers/ - the original directory for containers. (I bet you couldn’t have guessed that one 😜)
higherOrderComponents/ - Higher Order Components (HOCs) are a special type of container that are actually functions. These functions encapsulate reusable logic patterns and are used to wrap other components with that logic. For instance, one of our HOCs is a LazyLoaded component. This displays a loading indicator before the necessary data is loaded, and reports back to us if it takes too long. We pass any screens that need this loading behavior through the LazyLoaded HOC rather than having to re-implement the behavior within each one! 💥
layouts/ - This is the only other directory that holds presentational components. These presentational components are specifically concerned with how an entire page in our application is laid out.
screens/ - Screens are containers that pull in all of the presentational components and sub-containers for a particular application view. All of our screens start with a layout component and add children from there.

Each component has its own subdirectory within one of those parent directories. The main file in each subdirectory is index.js, which is where the general component definition goes. index.test.js is the test file that we automatically add via our scaffolding script. We also keep any styling for the component in this subdirectory. This includes any images it needs and a separate stylesheet.js file if the styles get too bulky to keep in index.js. We used Aphrodite to be able to write our styles in JavaScript, which helped us keep the styles localized to each component rather than buried in massive CSS files.

/models is where we defined classes for each of our API objects. Each class defined a toJSON() and a fromJSON() method which allowed us to transform JSON responses into instances while we worked with them inside the application, and then back to JSON when we had to send the data back to our servers. The project also uses Flow as a type checker, and transforming the JSON into more concrete data structures allowed us to properly type-annotate each field.

/modules is basically a directory for utility or helper code. We grouped closely-related code into their own files and ended up with modules like errorReporter.js and apiRequest.js.

store/ is for all of our Redux code. As I mentioned in my previous blog post, we separated our store into subdirectories for each of our models. Each of these subdirectories had the traditional Redux files of actions.js, reducers.js, and selectors.js. We additionally had a constants.js file for any constants relevant to that model store, and endpoints.js for functions that interact with our back-end API. At the store/ root, we have files that import all of the functions from the corresponding subdirectory files:

actions.js imports from all of the sub actions.js files
api.js imports from all of the sub endpoints.js files
rootReducer.js combines all of the sub reducers.js files
selectors.js imports all of the sub selectors.js files

We also have configureStore.js which does the initial setup of actually creating the store and potentially loading any previously saved state.

index.css holds our over-arching CSS styles. Most of our styles are inside our component directories, but there are a few body and html level styles that live in this file instead.

index.js simply renders our root React component.

registerServiceWorker.js sets up service workers so that we can serve assets from a local cache to make our application run faster.

Routes.js connects each of our screen components to an application route. For example, this is where we register our RegisterScreen to be loaded when the user visits the /register route in our dashboard.

Overall, we tried to structure our project such that all of the relevant code is nearby when we’re working on a specific part, while still maintaining a separation of concerns. Keeping smaller files grouped by model or component really helped improve the developer experience. We may continue to iterate on our structure in the future, but so far this has worked well for us! Let us know if you have any questions or if you do things differently at your company.

This post was originally published on the Nylas Engineering Blog

Raising the Limits on Developer Speed

Halla Moore — Wed, 24 Jan 2018 19:27:32 +0000

How we used React/Redux, Jest, and automation to rebuild our dashboard in only three months

Up until five months ago, our dashboard was slow, limited, and (worst of all) written in Angular. We don’t have anything in particular against Angular itself, but nobody on our team had any significant experience with it. This meant that fixing even a tiny bug took a large amount of effort. We had big plans to add awesome features to our dashboard — organizations, multiple applications per user, queryable logs, and more! — but we weren’t convinced that building on top of our legacy code was the best use of our time. So we scrapped it.

Our goal was to build the new dashboard in a way that would enable us to develop quickly and effectively. We knew we wanted to use React, to keep in line with our other in-house JavaScript projects, but the dashboard has a considerable amount of application state, so we decided to use Redux as well. We started by taking a bunch of pointers from Bumpers’ Isn’t our code just the *BEST* 🙄 article.

Instead of having all of our store files directly at the /store level, as is common in many Redux applications, we split the store into several subdirectories, each one with their own actions, reducers, and selectors files. Each of these subdirectories correspond to one of our models, e.g. Account, Organization, Application, etc. This made development much faster by grouping relevant code together. Now, when someone wants to make changes to the Account state, they only have to navigate to /store/accountto find that code, rather than having to ctrl+f in massive files that bunch all of the code for different models together.

Sidenote: Another point we took from the Bumpers article was the addition of an endpoints file in each of these store subdirectories. The API calls can be handled in this file and called in-turn by the actions file. This is a nice separation-of-concerns that makes it easy to switch out either the actions or the API interface without affecting the other, and provides a clean stub interface for testing.

This separation made it extremely easy to modify stores, but unfortunately, adding new stores required a lot of prep work. For each new store, we had to create a new directory, add a bunch of files, and write the same initial skeleton code — all work that could be automated! We wrote a scaffolding script to do it for us and added it to our package.json file. We were able to run this script with Yarn via yarn scaffold <type> <name>. We added several other pieces of skeleton code to this script, so we could create quickly components and model definitions as well as stores. This made the process of adding new code super easy and fast. Most of the code only needed a few details to be fleshed out and then it was good to go. 👍

Another thing that we did to increase our development speed was to use Jest for testing. We believe testing is an important part of development, but writing tests can significantly slow down the development process. Jest’s visual output is fantastic (on par with pytest for Python), but the real kicker is its concept of snapshots.

Using Jest’s snapshots is as simple as expect(testData).toMatchSnapshot(). The first time this test is run, the user will be prompted to inspect testData and confirm that it has the expected value. Jest then creates a snapshot file with the confirmed data value. On each subsequent test run, Jest will compare the current value of testData to the value stored in the snapshot. If the values do not match, the console will show the differences between the two values and ask if the snapshot should be updated.

This is much faster than having to 1) figure out what the value of data should be when initially writing the test (particularly if it has a complex structure), and 2) having to go change a bunch of hard-coded test values when something does legitimately change (which happens a lot in early development stages). We were able to add skeleton tests to our scaffold script, so each React component automatically got a test like this:

// @flow
import React from 'react';
import renderer from 'react-test-renderer';
import NewComponent from './index';

test('renders as expected', () => {
  const component = renderer.create(<NewComponent />);
  const tree = component.toJSON();
  expect(tree).toMatchSnapshot();
});

This helped ensure that all of our components were tested. If it was a simple component, the skeleton test was all it needed. If it was a more complex component, the test would fail and prompt the developer to update the test to be more accurate. This effectively eliminated the case where developers forget to write a test for a component, and not having to do any extra work to test the simpler components was a huge plus.

Sidenote: Prettier, an auto-formatter that we talked about in our tooling blog post, also did wonders for our development speed. You don’t realize how much time you spend on spacing until you no longer have to do it.

As these changes were integrated with our workflow, we were able to develop faster and faster. We completed the entire dashboard project (along with the associated backend changes necessary to support the new features we wanted to implement) in an astounding 12 weeks. The key lesson we learned from this experience was that investing the initial time into building a strong developing foundation is well worth the effort! For this project, building that strong foundation involved grouping code together in a functional way and automating as many patterns as we could. Going forward, we’ll be sure to look out for ways that we can do the same in our other projects!

We had a rising trend in the number of commits to the dashboard project, until it neared completion. This was with a team of 4-5 engineers, depending on the week.

This post was originally published on the Nylas Engineering Blog.