Remix’s products are write-heavy. In our transit planning product, users can quickly sketch out changes to bus routes, and Remix will show the resulting demographic and cost updates.

To manage these updates, we initially started with simple XHR requests and callbacks. Save something, and when that’s done, refetch the demographics and costs:

function saveBusStops(project_id, stops) {
  xhr({ 
    method: 'POST', 
    url: `${project_id}/bus_stops`, 
    json: {stops},
  }).then(() => 
    xhr({ url: `${project_id}/stats`})
      .then((body) => updateStats(body))
  );
}

This has a problem though. While drawing a new bus route, saveBusStops would get called many times in a row. So first we debounced it, every second or so:

const saveBusStops = debounce((project_id, stops) => {
  xhr({ 
    method: 'POST', 
    url: `${project_id}/bus_stops`, 
    json: {stops},
  }).then(() => 
    xhr({ url: `${project_id}/stats`})
      .then((body) => updateStats(body))
  );
}, 3000);

This worked fine for a while, but at some point we got larger customers, for which the /stats call would take several seconds to complete. This meant that sometimes the /stats call was still in progress when new bus stops were saved, which led to our core problem: overlapping API calls conflict with each other. While we’re querying the database in the /stats endpoint, the data changes because of a later /bus_stops call, which could cause the /stats endpoint to return incorrect data in the best case, or crash in the worst case (e.g. because of missing/changed ids).

Serializable transactions

The bugs resulting from this were hard to anticipate, track down, and fix. Initially we tried to solve this using serializable database transactions for all of our endpoints, guaranteeing a sequential order to transactions. While this fixed the bugs, it had a couple of downsides:

• PostgreSQL implements serializable transactions by throwing an error if two transactions conflict. You then have to retry those transactions. If those conflicts happen a lot (which for us they did), this significantly slows down endpoints.
• Slower endpoints meant that the problem of conflicts got worse, as more endpoint calls would conflict with each other.
• Our serializable transactions would take a lot of locks. When there are too many locks, they become less granular. Often entire tables would be locked by a transaction, which would cause them to routinely conflict with other transactions.

Other problems

Besides the problems with serializable transactions, the frontend code devolved into callback hell. Instead of just having to call the /stats endpoint, we introduced many different analytical models, which the user could turn on or off at will, and which all had different dependencies on different data that could change. This became hard to maintain.

We also ended up with a lot of debounced functions, with high timeouts, in order to mitigate the issues with slow endpoints. This meant that the user would have to wait sometimes several seconds before we would even start persisting their changes, and even longer before the models would refresh. This was a terrible user experience, especially given one of our main value propositions is a snappy, live-updating product.

So we had to come up with something better.

Introducing xhrQueue

We realised that we have a particular usage pattern. Each project could only be edited by one user at the time: the author of that project. Collaboration was still possible, but done by copying projects. This worked pretty well for our users, so we decided to exploit this usage pattern to make a simple change to solve a lot of our problems.

We made one additional assumption: that each user would typically be editing each project in only one browser window, on only one computer. We could even easily enforce this (by having the browser window request a “lock” on the project), but we found that in most cases this assumption holds well enough.

With these assumptions, we can move the sequential ordering of transactions from the database to the frontend, by simply queueing up network requests. This has a few advantages:

• No need for serializable transactions on the backend, removing all the problems of having to retry transactions, not granular enough locks, and so on.
• No need for callbacks, just queue requests up in order.
• Instead of debouncing, we can instead just remove duplicate requests from the queue.

This is how code ends up looking:

function saveBusStops(project_id, stops) {
  window.xhrQueue.xhr({
    method: 'POST',
    url: `${project_id}/bus_stops`,
    json: {stops},
    ignorePreviousByUrl: true,
  });
  window.xhrQueue.xhr({
    url: `${project_id}/stats`,
    ignorePreviousByUrl: true,
  }, (error, response, body) => updateStats(body));
}

The ignorePreviousByUrl will remove any existing requests in the queue that have the same URL.

More benefits

Once you have the basic model of a queue for endpoint requests, you can layer some optimizations on top. One would be to specify which requests are allowed to run in parallel, since they don’t conflict with each other. For now we have a simple optimisation like that: GET requests are allowed to run in parallel, since they are assumed not to mutate data. You can override this using overrideQueueItemType: 'read' or 'write'.

Another thing you basically get for free, is a system to retry saving when the connection drops. Just retry failed items in the queue until it works again!

Conclusion

For us, queuing up requests enabled us to build a better user experience while simultaneously resolving some tricky database issues.

We released the xhrQueue as open source. If your application has similar usage patterns, give it a try, and let us know how it works for you. We’d happily take contributions to make it better.

In the future we might want to loosen our assumptions and allow full-blown collaboration by multiple users on one project (OT!), but until then, this is a great stepping stone.

If any of this interests you, take a look at our open roles. We use all this to help create more livable cities. :)

How We Configure Jasmine

Testing front-end code is tricky. It’s full of asynchronicity (back-and-forths with the user and the back-end), browser-specific behavior (and bugs), visuals (the correctness of which can be fuzzy), and state (management of which is still much less mature than on the back-end, where we have fantastic decades-old databases). Therefore, it’s extra important to have good automated testing tools for the front-end.

At Remix we use various tools for this, which we’ve covered in the Preventing Regressions article. This time we’ll focus on Jasmine, our unit testing tool. Over the last few years we’ve built some configuration on top of it, all for very specific reasons, which we’ll look at in detail.

Our full setup is available as open source here. Maybe some day some of this configuration can be added to Jasmine by default! 📈

Random Test Order

First of all, we want to run our tests in random order, to prevent dependencies between tests. (This is one of the reasons we use Jasmine and not Mocha, which doesn’t support random test order.)

// Prevent dependencies between tests by randomizing tests.
jasmine.getEnv().randomizeTests(true);

The downside of this is that tests that are dependent on each other will sporadically fail based on the test order, which can be hard to debug. When you see such a failure in CI, you want to be able to run the tests locally in the same order so you can debug the problem. For this we can print the seed to the console:

// Generate our own seed so we can print it in the console,
// for CI debugging.
const seed = jasmine.getEnv().seed() ||
  String(Math.random()).slice(-5); // Same seed function as Jasmine
jasmine.getEnv().seed(seed);
console.log(`Jasmine seed used: ${seed}`);

Now we can just plug the seed into the URL like ?seed=12345. 🎉

Asynchronous Behavior

The trickiest thing in testing front-end code is probably dealing with asynchronous behavior, so we’ve spent a lot of time on setting this up right. There are two main approaches to this:

1. Keep the application code asynchronous, and in tests wait until the code is finished running before making assertions.
2. Stub asynchronous browser functions by introducing an artificial clock that we can move forward arbitrarily in tests to simulate time moving forward.

(1) has the downside of having to wait in tests for application code to finish. It can also be difficult to know exactly when it has finished—you have to always pass through a callback or Promise for the test to use. So we went with option (2).

First we set up fake clock and date, which is built into Jasmine. This replaces functions like setTimeout and new Date(). It’s important to do this before any libraries and polyfills are loaded, as they can store handles to those functions.

jasmine.clock().mockDate();
jasmine.clock().install();

Then there are some other asynchronous functions that Jasmine currently doesn’t replace, so we replace them ourselves. One example is setImmediate, which we can replace by a timeout with 0 milliseconds:

window.setImmediate = fn => window.setTimeout(fn, 0);
window.clearImmediate = id => window.clearTimeout(id);

Some libraries use it internally, in which case you’d have to call jasmine.clock().tick(1) in your tests. Another example is requestAnimationFrame, but there we want to replace it with at least 1 millisecond per frame, so we can step through it if we need to:

window.requestAnimationFrame = fn => window.setTimeout(fn, 1);
window.cancelAnimationFrame = id => window.clearTimeout(id);

We also install jasmine.Ajax to stub out calls to the server:

jasmine.Ajax.install();

Now there should not be any asynchronous waiting in tests any more! So we can tighten the timeout on asynchronous tests (in case you still want to use that syntax):

jasmine.DEFAULT_TIMEOUT_INTERVAL = 10; // milliseconds

Asynchronous Test Example

To see what an asynchronous test looks like with this setup, let’s try to test this function:

function ajaxCallWithTimeout(url, timeoutMs, onFinish, onTimeout) {
  let done = false;

  const xhr = new XMLHttpRequest();
  xhr.onreadystatechange = () => {
    if (!done) onFinish(xhr);
    done = true;
  };
  xhr.open('GET', url);
  xhr.send();

  setTimeout(() => {
    if (!done) onTimeout();
    done = true;
  }, timeoutMs);
}

This is what the happy-path test would look like:

it('calls `onFinish` when the request comes back in time', () => {
  const onFinish = jasmine.createSpy('onFinish');
  const onTimeout = jasmine.createSpy('onTimeout');

  ajaxCallWithTimeout('test.json', 100, onFinish, onTimeout);

  jasmine.clock().tick(99); // Move clock forward by 99ms.
  jasmine.Ajax.requests.mostRecent().respondWith({ status: 200 });

  expect(onFinish).toHaveBeenCalled();
  expect(onTimeout).not.toHaveBeenCalled();

  jasmine.clock().tick(20); // Move clock forward some more
  expect(onTimeout).not.toHaveBeenCalled(); // Still not called.
});

Hurray for arbitrarily manipulating time! ⏰

Tightening Asynchronous Tests

We noticed that we often want to make sure that at the end of a test nothing changes if you move forward time a bit more, like the last two lines of the test above. Typically this means that no more callbacks should be called, and no more Ajax requests should be made. We haven’t yet figured out how to do the first part (no more callbacks), but we did tighten against any more Ajax requests:

afterEach(() => {
  jasmine.Ajax.requests.reset();
  jasmine.Ajax.stubs.reset();

  jasmine.clock().tick(1000000);

  if (jasmine.Ajax.requests.count() > 0) {
    fail('Requests were made after the test.');
  }
  if (jasmine.Ajax.stubs.count > 0) {
    fail('Stubs were set after the test.');
  }
});

Promises

One more source of asynchronicity is Promises. According to the spec, handler functions should execute asynchronously. Because of this we use a Promise polyfill that internally uses setTimeout, even if the browser we run our tests in supports Promises natively.

We can even write a test to make sure Promises use the Jasmine clock:

it('uses the Jasmine clock', () => {
  const onThen = jasmine.createSpy('onThen');
  window.Promise.resolve().then(onThen);
  expect(onThen).not.toHaveBeenCalled();

  jasmine.clock().tick(1);
  expect(onThen).toHaveBeenCalled();
});

Tightening Tests

We try to tighten our tests as much as possible in order to catch as many bugs as possible, like how we tightened asynchronous tests above. Another example is not allowing logging to the console in any way. This catches errors and warnings from libraries, like React’s PropTypes. When legitimately logging to the console, you can still stub out the console method, which we do in a few places. We also ignore some logging by tools:

const oldConsoleFunctions = {};
Object.keys(console).forEach(key => {
  if (typeof console[key] === 'function') {
    oldConsoleFunctions[key] = console[key];
    console[key] = (...args) => {
      // Detect Karma logging to console.error 
      // by looking at the stack trace.
      if (key === 'error') {
        const error = new Error();
        if (error.stack && 
            error.stack.match(/KarmaReporter\.specDone/)) {
          return;
        }
      }

      // Don't fail tests when React shamelessly self-promotes.
      if (args[0].match && args[0].match(/React DevTools/)) {
        return;
      }

      oldConsoleFunctions[key].apply(console, args);
      throw new Error("Don't log to console during tests");
    };
  }
});

Another way to tighten tests is to make sure there are no DOM elements from tests left on the page after running a test, as that could leak state between tests. Since we always mount elements on <body>, we can just check if its number of children have changed:

let numberOfElementsInBody;
beforeEach(() => {
  numberOfElementsInBody = document.body.childElementCount;
});
afterEach(() => {
  if (document.body.childElementCount !== numberOfElementsInBody) {
    throw new Error('Forgot to clean up elements in <body>');
  }
});

This is an assertion on global state, to make sure it doesn’t leak between tests. The alternative would be to clear out the global state before each test (e.g. having a special <div> that all DOM elements get mounted into, and clearing it out before each test), which also works.

These are just some examples we came up with as we developed our product, but the principle of tightening tests can be more widely applied to any invariants you might have in your application. For example, on the backend you could check complicated database invariants that cannot be expressed as table constraints.

Conclusion

We showed how we configure Jasmine, but the underlying ideas are more widely applicable. For example, on the backend we use RSpec, which supports random test order, we stub out external requests using WebMock and Puffing Billy, and we tighten tests by running database invariant checks after each test and not allowing any warnings to be logged.

If you have any suggestions for how to configure Jasmine, be sure to leave a comment below. And of course we welcome contributions to our config! 🌟

If any of this interests you, take a look at our open roles. We care about livable cities even more than developer tools. :)

Fixing Bugs Forever

When fixing a bug, you want to make sure that it doesn’t appear again. The typical tool for this is adding an automated test, also called a regression test. But this is just one tool in our toolbox.

In this article, we’ll look at various techniques for preventing regressions that we use at Remix, such as screenshot tests, linters, commit hooks, approval tests, assertions, bot warnings, and conventions.

Cost vs. Effectiveness

When preventing regressions, there is often a tradeoff between cost and effectiveness. A technique is cheap if:

• it’s quick to write;
• it’s easy for others to understand;
• it’s reliable (no false positives);
• it’s loosely coupled (changing the code doesn’t require changing the detection of bugs);
• it executes quickly, and early on.

A technique is effective if:

• it covers as much as possible (ideally we prevent entire classes of bugs);
• it’s resilient to change (changing the code doesn’t affect us detecting the bug; it doesn’t lead to false negatives);
• it points immediately to the problem (no digging around required).

We’ll examine all our techniques in terms of cost and effectiveness. Ideal techniques have both, but as we’ll see, that’s hard to find!

Unit Tests

Let’s start with a traditional technique. A unit test runs a small piece of code in the actual codebase, and then makes some assertions on the result. Here’s an actual example from our codebase:

In this case, the cost is fairly low: it’s quick to write, easy to understand, runs quickly, and has never resulted in a false positive (as far as I know). It’s fairly loosely coupled, but would need updating if we change the API of the function, e.g. by changing the input from minutes to hours. In this case, it’s also fairly effective: we can be pretty sure that this piece of code works properly, even when changing it, and it immediately points to the problem when one of the tests fail.

But this is a pretty ideal case. Let’s look at another one, of a React component:

Still looks pretty straightforward, but in this case the test is less resilient to change: if we change the name of “onChange” to, say, “onEdit”, we might forget to update this test, which will make this test do nothing!

The reason is that in React, it is allowed to pass in properties that the component does not actually use. One way to make this test more resilient is disallowing that and instead throwing an error. That is basically an assertion, which we will look at in detail later.

Let’s look at one more, which has several problems:

In this case the component depends on global Ampersand state, which makes it hard to change this global state (e.g. by replacing it with Redux). We also have to deal with asynchronicity, as the component debounces changes to selectedMap. All in all, the test is not loosely coupled.

Overall, unit tests are cheapest and most effective for relatively small units which don’t require a world of context. And there is an upper limit to their effectiveness: they only test what you assert—rarely entire classes of bugs.

Screenshot Tests

Let’s look at another technique of preventing bugs from happening: screenshot tests. The way we use them, they are similar to unit tests, in that you run a small piece of code in your actual codebase, and make assertions. In this case, though, the assertions involve taking screenshots of what has rendered in the browser, and comparing that to previous screenshots.

We use Happo to take screenshots of “examples” (rendered components with specific properties) in our component library. This is such an example:

Fixing a bug in the timetable causes a bot to comment on the Github Pull Request, like this:

When clicking on the link, you would see something like this:

Screenshot tests like this are cheap: they are extremely easy to write and understand, and execute quite quickly. They are more loosely coupled to the code than unit tests typically are, as they don’t have to do any prodding into the DOM to make assertions. They are pretty reliable, with false positives only occasionally happening.

But most of all, they are effective: they cover so much at once — rendering logic of all the components in the tree, and even CSS. They point to problems in a direct, visual way. And they are fairly resilient to change, although one has to be careful to create new examples to explicitly cover bugs, otherwise it can become hard to determine what kinds of bugs a particular example is supposed to cover. They also have some side benefits: the examples serve as code documentation, and as a “component library” / “style guide”.

Screenshot tests are so effective at preventing bugs in rendering logic, that we often forgo having unit tests for that at all. We save unit tests for interaction and business logic, such as mutating state.

Approval Tests

Screenshot tests are like a big assertion that covers a lot of things. We can do something similar for text outputs: approval tests, where you store the text output of (for example) a JSON endpoint, and alert the programmer when it changes. Those text outputs are called the golden masters. In the backend we use the Approvals gem, which looks something like this:

Here we use a common fixture throughout the codebase, called map_with_lots_of_stuff, which contains various edge-cases. Because we use it in most of our tests, we know what to expect from it. And adding an edge case is easy: we just update the golden masters!

This is what the golden master for the test above looks like:

Since it’s checked into git, we get a nice diff view for free. And again, this is a cheap way of preventing bugs: extremely easy to set up and understand, just like the screenshot tests, and it runs just as fast as other backend tests. It’s fairly effective, too: you can cover the entire output of an endpoint with ease, especially with good fixture data that covers edge cases. When debugging, it gives a good indication of what might be going wrong, although it might be harder to trace down than with a pointed unit test.

It should be noted that approval tests can be flakey (false positives), especially if the order in which results are returned is poorly defined. So we changed our fixture framework to generate predictable IDs, and we changed the application logic to establish a well-defined order. This has the side-benefit that bugs become more reproducible.

Approval tests also have the same downside as screenshot tests: you have to be careful to be explicit about all the edge cases you are testing for. It can be confusing to have one fixture with all the things you want to test for. If that’s the case, just split out some separate tests. It’s cheap and effective, after all!

We’ve also started using Approvals for testing which SQL gets executed during an endpoint call, which can prevent certain performance regressions in a cheap way. Read more in our blog post on the topic, ORM: We Approve.

External APIs Reminders

We also use golden masters to warn programmers when they change an API used by an external service (as opposed to the front-end). Ideally, we would have systems test that boot up multiple services and test their integration; that would be effective. However, that is not always cheap: it can be tricky to write these tests, they are typically slow, and can be flakey.

Instead, our bot posts a comment (using a custom Pronto matcher) when the golden master of an externally used API changes to remind the programmer to manually test the integration. This can be cheaper for APIs that don’t change much and is still quite effective. It looks like this:

Linters

Linters are great to reduce discussion about code style, but they can also prevent bugs. For example, we once used Lodash’s find() method but forgot to actually include it, leading to confusing bugs, as the browser resolved it to window.find(). This was easily solved by adding a linter rule disallowing use of find() as a global method.

In this case, the effectiveness of the linter is limited (it only covers one particular case), but it’s extremely cheap to implement and use, especially because of the feedback cycle that is almost instant, if the programmer has an IDE that automatically runs the linter. If they don’t, it would be caught when committing, using Overcommit (our pre-commit hook tool).

Different Language

More elaborate than linting, is introducing extensions to the language, in order to prevent bugs. For example, Flow adds static type checking to Javascript. One could even go as far as using a different language altogether, such as Elm, which eliminates entire classes of bugs because of how the language is structured.

A classical example of this is C++ vs. Java. Traditionally, programmers had to manage memory carefully, making sure to deallocate memory when the last reference to an object was removed. This could cause memory leaks, a particularly hard kind of bug to track down. In modern languages such as Java—while keeping similar syntax as C++— has automatic memory management. A garbage collector automatically deallocates unused objects, which removes an entire class of bugs.

In our case, we use CSS Modules, which is an extension to the CSS language that adds better scoping of class names. We’ve never had clashing class names ever since.

Assertions

While tests and static checks can prevent a lot of bugs, they can rarely cover all combinations of user interactions. For this we use runtime assertions, which are checks in the application code.

For Ruby, we have written a small helper. In order to have it catch problems as early as possible, it raises an exception in tests and in development mode. When an assertion fails in production, we log an error to Sentry, but let the program continue executing. We use it like this:

It is very cheap to sprinkle assertions like this throughout your codebase. It can even serve as additional documentation for the code, by making any pre- and post-conditions explicit. They also have barely any performance overhead.

The effectiveness varies wildly per assertion. In this case, it’s in a file that gets called from many places in the codebase, making it more effective. Also, since assertions are embedded in runtime code, they rarely get out of sync (no false negatives). However, the team needs to be actively monitoring reported errors.

A special case of assertions that we use in the front-end (besides regular assertions), is immutable data. For example, Object.freeze() raises an error when trying to change a “frozen” object.

Data Integrity Checks

Another special case of assertions, data integrity checks make sure that persisted data (in a database) is of a certain form. For this we use several techniques. First, we try to use the most appropriate type for each column. Second, we use database constraints for simple checks. Third, for more complicated checks we have a script that runs queries against a follower database, and notifies us when an assertion fails.

These methods are increasingly expensive and decreasingly effective as they become more and more specific. But like other assertions, they operate on real-world data—full of edge cases—making it more likely to catch bugs with them than with tests.

“How can I prevent this bug from happening again?”

All these techniques are the result of us constantly asking ourselves the question: “How can I prevent this bug from happening again, in the cheapest, most effective way?” This is a more open-ended question than, “Is there a unit test for this,” or, “what is our test coverage percentage?” After all, there are more techniques than unit testing, and many of them are either cheaper, or more effective, or both.

To encourage asking this question, we have the convention to write a “test plan” in every commit. We have even configured Overcommit to remind us of this. These are some actual commits:

Note that the test plan doesn’t always involve writing code. Sometimes just testing something manually is enough, if the cost of automating it outweighs the chance that the bug regresses.

For different types of commits, different test plans are useful. For pure refactors, ideally you don’t need to change your tests. For bug fixes, you want to write how that bug—or similar ones—will be prevented in the future. For new functionality, think about how to guarantee its correctness.

Conclusion

We’ve looked at various techniques of preventing bugs from regressing and a way of evaluating these techniques. In the end, this is only what we came up with, and we are always looking for new ideas!

Most importantly, though, is the mindset. Whenever you fix a bug, think to yourself: how can I prevent this bug from happening again, in the cheapest, most effective way? And then extend this line of thinking to refactors and new functionality, too.

If any of this interests you, take a look at our open roles. We use all this to help create more livable cities. :)

We’ll start with our front-end build tools. We wanted to use the latest Javascript features without worrying about older browsers (Babel), confidence when changing CSS by scoping classes (CSS Modules), immediate feedback when changing code (React Hot Loader), and so on. All of this is easy to set up when using Webpack, which is why we switched to that. In this article we’ll look at how we’ve set this up.

Webpack config

There are a few ways we want Webpack to behave, based on the context. The first is dev-server vs static build.

• When developing we use the webpack-dev-server, which caches files in memory and serves them from a web server, which in turn saves time. It also supports hot module loading.
• When building on the Continuous Integration, or CI, server (we use CircleCI), or when deploying using Heroku, we want to generate a static build, so we can host them statically in production. That way we can set proper caching headers.

We also use both minified and non-minified versions of our builds, depending on whether it’s in production or still in development.

• In production, we want a gzipped and minified build, so it downloads and parses faster. We also enable all React optimisations, so it runs faster. Sometimes we also want to do this when developing locally, when measuring performance.
• Usually though, we want to disable minifying when developing. This way development is faster, as minifying is an additional step. We also want to get all of React’s warnings when developing.

To set this context, we use two environment variables, which we use like this in our package.json:

"scripts": {
  "build": "webpack",
  "build-min": "WEBPACK_MINIFY=true npm run build",
  "dev-server": "WEBPACK_DEV_SERVER=true webpack-dev-server",
  "dev-server-min": "WEBPACK_MINIFY=true npm run dev-server"
},

In our webpack.config.js we first set up some common stuff:

const config = {
  plugins: [ /* Some plugins here. */ ],
  module: {
    loaders: [ /* Some loaders here. */ ],
  },
  entry: {
    build: ['client/build'], // Our main entry point.
    tests: ['client/tests'], // Jasmine unit tests.
    happo: ['client/happo'], // Happo screenshot tests.
  },
  resolve: {
    alias: {
      client: path.resolve('./client'),
    },
  },
};

Nothing too exciting here. All our code is in the client directory, plus node_modules for libraries (which Webpack finds by default). We alias the client directory, so we can easily refer to it. We have three entry points, one for our app (client/build.js) and two for tests (which we’ll get into in a later article).

We then look at if we’re minifying or not:

if (process.env.WEBPACK_MINIFY) {
  config.plugins.push(new webpack.DefinePlugin({
    'process.env': {
      // Disable React warnings and assertions.
      'NODE_ENV': JSON.stringify('production'),
    },
    '__DEV__': false, // For internal use.
  }));
  config.plugins.push(new webpack.optimize.UglifyJsPlugin({
    compress: { warnings: false },
  }));
} else {
  // Only use source maps when not minifying.
  config.devtool = 'eval-source-map'; 
  config.plugins.push(new webpack.DefinePlugin({
    '__DEV__': true,
  }));
}

If we’re minifying, we want to set NODE_ENV to “production”, as React uses this to strip away all sorts of assertions and warnings, making it faster. When not minifying we enable source maps.

Then we have setup specific for when using the dev-server:

if (process.env.WEBPACK_DEV_SERVER) {
  // Development configuration, assumes this is loaded with 
  // webpack-dev-server, running on port 8080 (default).

  // Hot loading for build.js.
  config.devServer = { noInfo: true, host: '0.0.0.0', hot: true};
  config.entry.build.unshift(
    'webpack-dev-server/client?http://localhost:8080');
  config.entry.build.unshift('webpack/hot/dev-server');
  config.plugins.push(new webpack.HotModuleReplacementPlugin());
  config.plugins.push(new webpack.NoErrorsPlugin());

  // React components hot loading.
  config.module.loaders.unshift({
    test: /\.js$/,
    include: path.resolve(__dirname, 'client/components'),
    loader: 'react-hot',
  });

  // Expose Jasmine test page as index page on http://localhost:8080
  config.plugins.push(new JasmineWebpackPlugin({
    htmlOptions: {
      chunks: ['tests'],
      filename: 'index.html',
    },
  }));

  config.output = { 
    publicPath: 'http://localhost:8080/',
    filename: '[name].js',

    // In case this is run without webpack-dev-server.
    path: 'public/client',
  };
}

• We initialise the dev-server with noInfo, making it less verbose, and bind it to 0.0.0.0 so you can access it from other machines on the network (useful for debugging).
• We enable Hot Module Replacement, per instructions here. We also enable the React Hot Loader, but only on actual React components (client/components).
• Then we host the Jasmine index page on the same port, so you can just navigate there to run the tests.
• Finally we set config.output to something simple, so you can easily view what is generated at http://localhost:8080/build.js. In case we run this without the dev-server (which should typically not happen), we write to where other static files are written.

If we’re not running the dev-server, we’re writing to disk:

else {
  // Static configuration, outputs to public/client.
  // For use with Heroku/CircleCI.

  if (process.env.WEBPACK_MINIFY) {
    // Gzip.
    config.plugins.push(new CompressionPlugin());
    
    // Generate stats.html.
    config.plugins.push(new StatsPlugin('stats.json'));
    config.plugins.push(new Visualizer());
  }

  config.output = {
    path: 'public/client',
    publicPath: '/client/',

    // Unique filenames (for caching).
    filename: '[id].[name].[chunkhash].js',
  };
}

• When minifying, we gzip all files (which Rails static asset hosting automatically uses), and we generate a file usage visualisation, which we serve on our internal development pages.
• We also generate unique filenames for each build, so we can serve them with infinite caching headers.

Finally we speed up deploys a bit by leaving out tests when deploying on Heroku:

// Don't build tests when deploying on Heroku.
if (process.env.HEROKU_APP_ID) {
  delete config.entry.tests;
  delete config.entry.happo;
}

Serving from Rails

Let’s now look at the plugins part of our Webpack config. It looks like this:

plugins: [
  new CircularDependencyPlugin(),
  new ManifestPlugin(),
],

The first one is to prevent circular dependencies, which can be a pain to debug in Webpack. The second one generates a manifest.json file, which looks something like this:

{
  "build.js": "0.build.fc79868b1fdedc95cd1f.js",
  "happo.js": "1.happo.d44f048f66291e0e73ca.js",
  "tests.js": "2.tests.305167cc0309faddc140.js"
}

We use this in our Rails application to serve the right assets. For this we have created a helper file, assets_helper.rb:

# Adds `webpack_include_tag`.
module AssetsHelper
  def webpack_include_tag(filename)
    if Rails.application.config.use_webpack_dev_server
      # Assumes that Webpack is configured with
      # config.output.filename = '[name].js'.
      return javascript_include_tag(root_url(port: 8080) + filename)
    end

    webpack_filename = webpack_manifest[filename]
    if webpack_filename
      javascript_include_tag("/client/#{webpack_filename}")
    else
      raise ArgumentError, "Webpack file not found: #{filename}"
    end
  end

  private def webpack_manifest
    @webpack_manifest ||= JSON.load(Rails.root.join(
      'public', 'client', 'manifest.json'))
  end
end

This allows us to call webpack_include_tag(‘build.js’) in templates, and have it use the filename including the hash. Now we can tell the browser to cache these files forever, as they will have a different filename if they ever change.

Note that when use_webpack_dev_server is enabled, we point to the dev-server. We set this variable to true in development, to false in staging and production, and in test.rb we set:

config.use_webpack_dev_server = !ENV['CI']

Preprocessing using Loaders

Finally, we have a bunch of Webpack loaders. This is what that looks like in the Webpack config:

module: {
  loaders: [
    {
      test: /\.js$/,
      include: path.resolve('./client'),
      loader: 'babel',
      query: {
        cacheDirectory: '.babel-cache',

        // For code coverage.
        plugins: (!process.env.WEBPACK_DEV_SERVER &&
          !process.env.WEBPACK_MINIFY) ? ['istanbul'] : [],
      },
    },
    {
      test: /\.less$/,
      include: path.resolve('./client'),
      loaders: [
         // Inject into HTML (bundles it in JS).
        'style', 

        // Resolves url() and :local().
        'css?localIdentName=[path][name]--[local]--[hash:base64:10]',

        // Autoprefixer (see below at `postcss()`).
        'postcss-loader',

        // LESS preprocessor.
        'less', 
      ],
    },
    {
      test: /\.(jpe?g|png|gif)$/i,
      include: path.resolve('./client'),
      loaders: [
        // Inline small images, otherwise create file.
        'url?limit=10000',

        // Minify images.
        'img?progressive=true',
      ],
    },
    {
      test: /\.(geo)?json$/,
      include: [
        path.resolve('./client'),
        path.resolve('./spec'), // Shared fixtures.
      ],
      loader: 'json',
    },
    {
      test: /\.svg$/,
      loader: 'raw',
    },
  ],
},
postcss() {
  return [autoprefixer];
},

• First, the Babel loader. This allows us to use the latest Javascript features without having to worry about browser support (in conjunction with babel-polyfill). We use Istanbul to track code coverage for tests, and we set an explicit cache path so the CI can keep this cache between builds. This is what that looks like for CircleCI, in circle.yml:

dependencies:
  cache_directories:
    - ".babel-cache"

• Next is CSS. We use LESS for preprocessing, although we’re thinking of switching to PostCSS, which uses future CSS standards. We already use PostCSS for auto-prefixing. We also use CSS Modules by setting css?localIdentName, which lets you scope CSS classes to only the file that uses them.
• Images are being inlined if they are a small file, otherwise they get loaded separately. They are also minified.
• JSON and SVG are straightforward. We import SVG as text, which we use with an <Svg> component that looks like this:

// Use a tool like https://jakearchibald.github.io/svgomg/
// to slim down the SVG, and then manually
// remove width/height/fill/stroke.
const Svg = React.createClass({
  propTypes: {
    height: React.PropTypes.number,
    offset: React.PropTypes.number,
    svg: React.PropTypes.string.isRequired,
    width: React.PropTypes.number.isRequired,
  },

  render() {
    return (
      <div
        className={styles.root}
        dangerouslySetInnerHTML={{ __html: this.props.svg }}
        style={{
          height: this.props.height || this.props.width,
          width: this.props.width,
          top: this.props.offset,
        }}
      />
    );
  },
});

export default Svg;

Which then gets used like this:

<Svg svg={require('./pencil.svg')} width={14} offset={2} />

Conclusion

This is just a small part of our stack, but it took a while to get right. After all, it’s the small things that make a difference, such as being able to run a minified version with all React optimisations in development, or persisting Babel’s cache between CI runs, or not building tests when deploying.

Hopefully this is useful to get started with Webpack, or to tune your existing setup. Keep an eye out for next editions in this series, in which we’ll talk about our components library, unit testing, screenshot testing, deploying, keeping the CI fast, and more!

A few months ago I was riding the subway taking positions on the Brigade web app. I noticed something strange. Whenever I didn’t have a strong opinion I checked out the reasons people had left to inform myself. Then I would use the back button to take positions again, only to have to scroll down all the way to where I was before. That was a bad experience—I had to do a lot of scrolling—especially since I like to take a lot of positions!

Now, I had done the same thing in Chrome on my MacBook before, and I never noticed this problem. When I got home, I verified this, and indeed, it worked fine on my laptop—it scrolled back to my last taken position. Then I tried out other browsers on my laptop, such as Firefox and Safari, and aha! Those browsers had the same problem as my iPhone. I found it so annoying that I started investigating.

It turns out that all browsers restore the scroll position when clicking the back button, right after the page has loaded. However, with single page applications like ours, a page load typically doesn’t mean all content on the page is available; we first need to make some AJAX requests before we can render things. So for traditional websites most browsers work fine, but for newer web apps navigating around can suck—except in Chrome.

Existing solutions

After digging through the Chrome source code, I found the piece of code responsible for restoring the scroll position. It turns out that Chrome uses some sophisticated logic to determine when to restore the scroll position, which looks at if network requests have completed, if the size of the page has changed since last looking at it, if the user has already scrolled, and so on. A personal highlight is the variable canRestoreWithoutAnnoyingUser.

It turns out that this is such a debated topic in the react-router community, that they even split out a separate repo for different scroll behaviours.

Looking at how other people solve this problem, I found that our navigation library at the time, pjax, had functionality for caching page content when navigating away, so that pages can be immediately restored when navigating back. However, it assumed having static content, and didn’t seem to play well with React, which we use for our rendering, as React components would lose their state.

We were considering switching to react-router (which we have now done), so I looked if they had a better solution. It turns out that this is such a debated topic in the react-router community, that they even split out a separate repo for different scroll behaviours. Unfortunately, none of them supported waiting for the content to be rendered, like Chrome did.

Writing our own polyfill

So I decided to write my own solution. I really liked Chrome’s behaviour, so I wanted to write a polyfill that would emulate it as closely as possible. A key part of Chrome’s algorithm was to wait until the page becomes large enough to actually be able to scroll to previous position again, and that seemed easy enough to implement. Instead of waiting for network requests to finish, I simply checked the page width and height every few milliseconds, and that seemed to work well enough. Then, when it would be possible to scroll, do it. With manual testing of scroll values, that seemed to work pretty well.

The next question is, where to scroll to? Our application uses the History API for all page navigation, so I decided not to worry about full page loads. It turns out that you can store information whenever calling pushState or replaceState, so I modified both functions to store the scroll position whenever calling them. Combining that with restoring the scroll position when popState is called, and it already comes pretty close to Chrome’s behaviour!

Interestingly, people have argued that this is a bug in the spec, and in fact Chrome has deliberately implemented this differently.

Those modifications worked well for navigating to new pages, but not so much for pressing “back” and then “forward” again, because we didn’t save the scroll position from before clicking the “back” button. So I wanted to also store the scroll position when popState was fired, because that means that the browser navigates to another place. However, it turns out that’s not so easy, because the spec states that the scroll position should be restored before firing popState, so we would not be able to determine the actual scroll position. Interestingly, people have argued that this is a bug in the spec, and in fact Chrome has deliberately implemented this differently. So I had to do without scroll restoration when pressing the “forward” button.

Another deviation from Chrome’s behaviour, is that it doesn’t attempt to restore the scroll position if the user has already scrolled. Unfortunately, in Javascript-land there is no way for us to tell if a scroll was initiated by the user, or by the browser’s scroll restoration algorithm (which, as we just learned, is even inconsistent across browsers, so it’s hard to make assumptions about it). Luckily, both this problem and the popState problem will likely be fixed by the Custom Scroll Restoration Proposal, a new API that allows Javascript developers to disable the browser’s scroll behaviour altogether. It has already been shipped in—you guessed it—Google Chrome. Hopefully other browser vendors will follow suit soon.

Anyway, we’ve had this polyfill enabled on Brigade’s production web app for a few months now without any problems, so we decided to make it open source. If you have similar scrolling issues with your web app, just install the delayed-scroll-restoration-polyfill. And, as always, we welcome all feedback!

The hardest thing when building a large application is managing complexity. You get complexity when lots of parts of your application interact with each other, resulting in a large number of states your program can be in. This makes it harder to reason about your program.

Frameworks like React help us to reduce this complexity by decomposing an application into smaller components which can be reasoned about individually. But unless we are careful, we can still end up with a lot of complexity within our components. Think of that one component that accepts more than 10 properties — isn’t it a pain to work with? Each additional property increases the API surface, causing a combinatorial explosion, which makes it hard to predict how a change to one prop will affect all the possible combinations.

For example, in our codebase at Brigade we have a <Button> component that has grown significantly over time — as these things happen. At one point it took a color string, flat boolean, zDepth integer (a Material Design term), unstyled boolean, light boolean, dark boolean, darkRipple boolean, round boolean, type string, and many more. Besides weird inconsistencies (what does it mean to have <Button dark light>?), it was mostly just hard to change anything. What if we change some shadow, will that still look good for <Button color=”primary-inverted” flat zDepth=”3" round>? Do we even have a button with those properties? The only way to work with such a component is to try to understand how all the different properties interact, and come up with all the possible results in your head, which is impractical.

While a dozen properties is bad, imagine that you suddenly add hundreds of properties to a component. Can you imagine how much complexity that adds? You have no idea how all those properties are being used throughout the application, and what interactions they might have with the changes you are making.

That’s exactly what happens when you pass in a CSS class as a property.

I’ve seen the pattern of passing a CSS class into components a couple of times now. Superficially it makes sense, because it is consistent with the built-in components, and you want to be able to style your components, right? For example, we could have <Button className=”sign-up-submit”>, with corresponding CSS that overrides the global styles for <Button>.

However, that className is complexity in disguise. Once you can give a component any arbitrary CSS class, you can change any of its 315 CSS properties, which has exactly the same problem as adding 315 properties explicitly. With any change you have no idea how it might interact with all the different CSS properties that might be applied to the component throughout the application, making the component very brittle. And if you do this throughout the application, expect styles to break all over the place.

So what to do instead? First of all, you can make all different styles explicit properties. Unfortunately you can end up with lots of properties, like with our <Button> component, but at least then these properties are explicit — the complexity is not hidden.

For example, we had a <Checkbox> component which took a className, which we used in one case to vertically align a (rather complex) label, and to add an ellipsis if it would overflow. In other cases, however, the label would wrap to the next line. Instead of solving this with className (which actually broke when we changed the component’s styles!) we could expose a wrap property that allows choosing between the wrapping and overflow ellipsis behaviours.

The second trick is splitting one component into two or more components, which have sufficiently different styles or behavior. In some cases you can use composition, such as extracting a component that just renders a shadow — which you can then reuse! The only potential downside is that you can get more elements, which in certain rare cases might hurt performance.

To see if a component has a truly small API surface, just look at your test suite. Does it reasonably cover all possible combinations of properties, or does it miss some major use cases? If you have a className property, your tests will most certainly not cover all the things you could do with the component. But CSS classes are only one example of properties in disguise. The same applies to a style property; a function that can alter a component’s rendered output significantly; many references to stateful objects (such as stores); multiple mixins that add properties, and so on.

So, to keep your application maintainable:

• Keep the number of properties of your components to a minimum.
• Don’t sneak in more properties implicitly through className.
• Represent actual different ways a component can look or behave using properties.
• Split out your component into several smaller components that you can compose.

Your application will become easier to reason about, and thus easier to change.