Component Data Versioning

Problem

One of the major hurdle with the Clay component architecture is iteration. It’s rare that a component is built once and then never iterated on again. While changing HTML, CSS or JS of a component is easy, what happens when you decide you need to iterate on a component’s schema? Once you make a change in your component’s schema, your data for all future instances of your component will diverge from previously created instances and this could break your pages.

Solution

Rather than writing scripts to run again your Clay instance to modify old data, what if components could control their own data versioning and be upgraded on the fly? This is where data versioning comes in. By assigning a version number in your component’s `schema.yml`and providing a module which declares upgrade logic, Amphora can dynamically upgrade components as you request your data.

Implementation

For the complete discussion of data versioning please refer to the [original issue](https://github.com/nymag/amphora/issues/398) for the feature. In the following sections we’ll cover requirements and implementation details of the feature.

Requirements

• Either a model.js or no server-side logic for the component

• A _version value in your component’s schema with major and minor version (i.e. _version: 1.0)

• An upgrade.js file which exports functions that correspond with _version numbers

Example of an upgrade.js file:

'use strict';

module.exports['1.0'] = function(uri, data, locals) {

  // Some logic to modify the return object. Must return component data

  return data;
}

As you’ll notice, the function signature of an upgrade function is the exact same as a model.js render or save function. The only requirement is that these functions return the component data that has been upgraded, but otherwise you’re free to do anything. Just remember that when these functions are run a user is requesting data, so keeping the upgrades quick will benefit your end users.