Motivation<\/h3>\n
If you have been following Meteor blogs, you are likely aware that React has factionalized the community. Rumblings about React began in 2015 as\u00a0<\/i>Sacha Greif, the author of Discover Meteor<\/em>, published a series of articles that explain how to migrate a Meteor application from Blaze to React. Then, in November 2016, Meteor guru Arunoda Susiripala bid farewell to the Meteor community, moving on to work on Next.js, a minimalistic React framework.<\/p>\n These events piqued my interest, and I began to evaluate React in earnest. I decided to convert a production application named\u00a0Incentive Sherpa\u00a0<\/em>from Blaze to React. I took this aggressive approach because I feel that no tutorial can give one the depth of experience that can be gained by committing to a real project and pushing it through to completion.<\/p>\n I had originally estimated that the project would require 60 days, but it ended up taking over 100 days. To put this in perspective, understand that Sherpa was a medium-sized, multi-tenant SaaS application based on Meteor 1.3. It incorporated a variety of third-party packages that are the hallmarks of a typical enterprise application. Sherpa used the so-called advanced<\/em> Bootstrap implementation which facilitated control over appearance and layout via configuration variables.<\/p>\n Sherpa size metrics:<\/p>\n Although Sherpa was in good technical shape to serve as the baseline for the conversion effort, the system had a lot of redundancy, primarily due to evolution. Over time, new subsystems were tacked on by cloning existing subsystems and modifying them to meet requirements. Suffice it to say that the system could benefit from some refactoring.<\/p>\n My guiding philosophy for the conversion process:<\/p>\n You can embed React components into Blaze templates using package react-template-helper<\/strong>. My very first React component was created and tested using this approach. Theoretically, you could use react-template-helper<\/strong> to incrementally convert an entire application into components, starting with low-level Blaze templates and then building upwards to create higher and higher level components until all templates have been systematically replaced. This approach would make it possible to keep the system functional at all times, at the expense of some additional testing and the creation of some throw-away code.<\/p>\n Package\u00a0react-template-helper<\/strong> is ideal for developers experimenting with React; however, I decided against using it because I was committed to a comprehensive conversion process that would ultimately eliminate Blaze.<\/p>\n You can use BlazeLayout and ReactLayout together in the same application. Certain routes are rendered by Blaze while others are rendered by React.<\/p>\n I tried to use this approach but I encountered difficulties. Since Blaze and React render HTML into different root<\/em> HTML elements, the system failed to clean up after route changes, causing defunct pages to linger in the DOM, screwing up the UI.<\/p>\n Although I was able to circumvent this problem by dynamically adding\/removing CSS classes to control the visibility of pages generated, I considered this to be a hack, so I was hesitant about pushing a hybrid Blaze\/React system into production and decided against it.<\/p>\n I began performing the conversion effort on an isolated GitHub branch. I was taking my time with no hard deadline, and had no requirement to keep the system working at all times. I decided to abandon the incremental approach and began converting entire subsystems all at once.<\/p>\n I began my conversion effort with a small subsystem called Events, <\/em>an administrative page that displays a list of event records:<\/p>\n I printed a screen shot of the Events page and used a pen to circle elements in order to plan my component hierarchy. I initially came up with this component outline:<\/p>\n I quickly realized that the Events subsystem would require more effort than I had anticipated. There would be extra work to create universal shared layout components, such as the top bar, plus the off-canvas navigation panel fly-out that appears when the user touches the burger button. I decided to work on these shared layout components first.<\/p>\n The need to support layouts led me to Arunoda\u2019s React Mounter (NPM react-mounter<\/strong>), which is ideal for converting a typical Blaze application that uses layout templates. React Mounter allows you to mount a hierarchy of components by specifying a layout<\/em> component plus a content<\/em> component. React Mounter does everything necessary to mount the layout component as a container with the content component serving as the body.<\/p>\n I added react-mounter<\/strong> to my tech stack and began experimenting with it. The package worked beautifully, and I wholeheartedly recommend it for any application that uses reusable layouts.<\/p>\n From a developer\u2019s perspective, a React-rendered browser page can be seen as a hierarchy of components. The entire browser page is typically represented by a top-level container component that includes many nested components; together, these components represent the page that the user sees.<\/p>\n A component is declared as a JavaScript class. Ideally, each component should be declared in its own JSX file to facilitate easy reuse.<\/p>\n Using JavaScript import<\/strong> statements, parent components can reference to child components, effectively declaring a hierarchy.<\/p>\n At run time, when the user chooses a route, FlowRouter<\/strong> will mount<\/em> (i.e., instantiate) the top-level component of that route. After invoking several life-cycle methods, the React mounter will start a process that causes the components to build the HTML page.<\/p>\n Each component must have a\u00a0render <\/strong>method, which is written by the developer. The render<\/strong> method must return either raw HTML, one or more child components, or a combination of the two.<\/p>\n When React renders a top-level component, it will indirectly render referenced subcomponents. React renders the hierarchy of components in a carefully choreographed dance, resulting in the HTML page that the user ultimately sees.<\/p>\n Components render HTML in accord with their properties\u00a0<\/em>which play the role of the model <\/em>in the MVC design pattern. In a well-structured React application, the HTML rendered by a component is exclusively a function of the render<\/strong> method and the properties supplied to the component. Properties are the model, the component is the controller, and the rendered HTML is the view.<\/p>\n After the initial rendering, React keeps all component instances in memory. Those component instances play an ongoing role: any changes to properties will cause the component to dynamically re-render its respective HTML. This is how React facilitates reactive<\/em> behavior which is familiar to Meteor developers.<\/p>\n React offers two ways to declare components: ES6 classes<\/em> or functions<\/em>. Moreover, rendering logic can be expressed as either JSX or straight JavaScript. I chose to use ES6 classes as JSX, which is currently the preferred way to use React.<\/p>\n Seasoned React developers segregate their components into two broad categories: higher-order components <\/em>(HOCs) and components<\/em>:<\/p>\n In a Meteor\/React application, HOCs set up subscriptions and fetch data. A typical Meteor HOC will have only a single method\u00a0withTracker<\/strong>\u00a0that fetches data from various sources and uses it to build a properties object. The HOC supplies the properties object to a lower-level component (henceforth subcomponent<\/em>).<\/p>\n It is best practice to have the HOC and its subcomponent share the same name, except the HOC name will have the suffix Container<\/strong> appended. Example:<\/p>\n While an HOC is tightly coupled with one subcomponent, a given subcomponent may receive properties from many different HOCs. This ability to reuse a single component from different HOCs is an important technique for maximizing component reuse.<\/p>\n HOCs do the heavy lifting in a Meteor\/React application. They can be somewhat difficult to code and test because they deal with database queries and because method withTracker<\/strong> is reactive<\/em>. Updates to any database collections referenced within withTracker<\/strong> will cause withTracker<\/strong> to be automatically re-executed, causing the HOCs subcomponent to be re-rendered. This occurs because withTracker<\/strong> serves as both<\/em> an imperative function and<\/em> an event listener. This crazy behavior will be hauntingly familiar to seasoned Meteor developers, <\/em>whom are nodding their heads in agreement as they read this. React improves on Blaze by encapsulating this tricky logic inside HOCs. This encapsulation makes it easier to pinpoint problems, ultimately reducing cost.<\/p>\n A well-written subcomponent will never directly invoke a MongoDB fetch operation, but will instead render HTML in accord with supplied properties. Subcomponent rendering logic should refer only to neutral component properties, which can be seen as the\u00a0source of truth<\/em>\u00a0governing all rendering decisions.<\/p>\n Dividing responsibilities between HOCs and normal components is an excellent way to separate concerns. Many React developers enthusiastically support this approach, because it clearly separates the concern of data fetching from the concern of rendering. This approach also makes normal components easier to reuse.\u00a0 As long as an HOC can be written to supply the expected properties, the normal component can function properly in any usage scenario.<\/p>\n A Meteor\/React application will consist of a mixture of HOCs and normal components. There are two approaches to using HOCs:<\/p>\n While there is no right or wrong answer, I personally tend to use many narrowly-focused HOCs. This minimizes property handling by keeping HOCs close to subcomponents that they feed.<\/p>\n You will need to decide on the proper\u00a0granularity<\/em> of your components. While there are no hard-and-fast rules, I’ve discovered a technique that you may find helpful.<\/p>\n If you notice repeating patterns of HTML in your render<\/strong> method, you can eliminate redundancy by breaking out the repeating HTML into a reusable component. If you DRY, you will create more components than you had expected. I had guessed that Sherpa would require a few dozen components, but by the time the conversion effort was completed, I had authored 64 HOCs and 168 normal components, a total of 232 components.<\/p>\n By the way, early in the project, I struggled with a kind of psychological aversion to creating new components. I was primarily concerned about performance. Yet, after some experimentation, I found my performance concerns were unfounded. I was seeing excellent performance, better than Blaze in most instances, even in subsystems with hundreds of components.<\/p>\n Once my concerns had been put to rest,\u00a0I proceeded to create components with wild abandon.\u00a0Now, I can create new components effortlessly, and surprisingly, those components will often work correctly the first time without debugging.<\/p>\n When you create a large number of components, standards and naming conventions become super important. Here are some standards that I choose to abide by:<\/p>\n In many cases, there will be a one-to-one correspondence between an HOC and its contained component. However, it will occasionally be advantageous to define multiple HOCs that wrap the same<\/em> component. Consider this example:<\/p>\n Both OffCanvasNavStandardContainer<\/strong> and OffCanvasNavDiagContainer<\/strong> serve as wrappers for OffCanvasNav<\/strong>. Each HOC may have completely different subscriptions and different rules for fetching data. This is absolutely fine, as long as both HOCs supply properties as necessary to meet the requirements of subcomponent OffCanvasNav<\/strong>.<\/p>\n Behind every Blaze template there exists a tree of objects called the data context<\/em>. Under Blaze, the data context plays the role of model in the MVC design pattern.<\/p>\n Blaze provides the developer with several options for setting the data context of a Blaze template, but by far the most common approach is to allow Iron Router to provide it. For each route path, Iron Router fetches and returns a tree of objects which comprise the data context of that route. Instructions for retrieving data context objects must be expressed by the developer in the Iron Router data<\/strong> function, which is part of each route descriptor. Iron Router provides the data context to Blaze so that templates can refer to it during HTML rendering.<\/p>\n Meteor developers tend to complain about the way Iron Router deals with data contexts. Hard-core Meteor insiders characterize it as an anti-pattern<\/em>, and they have devised clever ways to improve the situation. One solution is to remove Iron Router from the system, add FlowRouter, and then use template-level subscriptions. This approach is recommended by many Meteor gurus, and I agree with them wholeheartedly. But for clarity, I will compare the design of a typical, clunky Blaze application, in which Iron Router establishes data contexts, with a modern React application.<\/p>\n One problem with Blaze is that it treats the data context as the sole<\/em> input into the template rendering process. There is no easy<\/em> way to configure a template to appear or behave differently in different usage scenarios. For example, consider an ostensibly-reusable template that renders a user list into HTML. In some scenarios, the user list may need to be selectable, while in other scenarios, selection of the user list must be inhibited. In order for the user list template to be easily reusable, there should be a convenient way for the developer to configure the template to behave differently in different scenarios. Ideally such configuration settings would be supplied by the parent (i.e., calling) template.<\/p>\n Another problem with a typical Blaze application is that data contexts are monolithic;<\/em> there is only a single tree of data for each route, and that tree must contain the union set of all<\/em> data needed by all<\/em> templates used within that route.<\/p>\n This monolithic data context makes it hard to write reusable templates. Clearly, templates must know the names of fields in the data context, but they must also be intimately aware of the structure<\/em> of the data context in order to successfully navigate via Blaze functions such as Template.currentData and Template.parentData. These navigational functions are hard-coded into the supposedly-reusable template. Consequently, a reusable template becomes\u00a0tightly coupled<\/em> with a specific data context. Attempting to reuse that template elsewhere will require coding changes to replicate those portions of the data context required by the reusable template. The effort to keep data contexts in sync with ongoing enhancements to templates makes Blaze programming more tedious than need be.<\/p>\n React eliminates this problem by allowing each component to explicitly declare its information needs (i.e., properties), tantamount to a schema. At runtime, HOCs perform retrieval functions and then supply data as properties to lower-level components. If those properties fail to satisfy the declared requirements of lower-level component(s), the application will fail with a clear explanation logged to the developer console. Such problems can be fixed very quickly at low cost.<\/p>\n In contrast to a legacy Blaze application with monolithic data context, a React route can have many<\/em>\u00a0HOCs at different levels, tantamount to having\u00a0many<\/em> data contexts. This means React applications tend to have better encapsulation<\/em> than Blaze applications. Better encapsulation makes it easier to develop reusable component that work predictably and reliably in different usage contexts, even if those components require complex configuration settings.<\/p>\n Of course, there is no free lunch, and React components take more time to develop than standard Blaze templates.<\/p>\n The bottom line is that Blaze allows developers to cut corners in a way that seems perfect for churning out proof-of-concept MVPs while React engenders industrial-strength discipline that screams this is enterprise software.<\/em><\/p>\n Near the end of the Sherpa conversion effort, I formally separated the reusable components and subsystems from their application-specific counterparts by splitting the code into two separate GitHub repositories:<\/p>\n As the conversion effort entered its final phases, I started testing VXFrame independently of Sherpa to ensure that it would function properly as a stand-alone project. In this process, I ended up fixing many longstanding issues and improved code organization.<\/p>\n When the conversion effort was finally complete, VXFrame had many key features that you\u2019ll find in a typical multi-tenant SaaS including:<\/p>\n In addition to reusable code, VXFrame provides examples<\/em>, patterns<\/em> and programming conventions<\/em> that can make it easier to develop new application-specific subsystems.<\/p>\n Since React and Meteor are super-flexible, the onus is on the developer to decide how to implement required features and to select the best third-party packages. Ironically, this flexibility can make it difficult to choose the best path forward. For better or worse, VXFrame is opinionated, and it offers clear patterns for implementing new subsystems.<\/p>\n VXFrame can reduce costs by reducing third-party package research. It includes dozens of third-party packages that are proven to work well together. New application-specific subsystems can be created at low cost by cloning VXFrame subsystems, then modifying them to suit. Alternatively, in cases where a proposed subsystem bears no resemblance to any existing VXFrame subsystem, it is possible to add third-party packages and to code new subsystems from scratch, while still leveraging VXFrame services and patterns.<\/p>\n VXFrame is intentionally\u00a0layered<\/em>\u00a0to allow developers to override default behaviors or subsystems with application-specific logic. If default behaviors are acceptable, the application-specific customization layer<\/em> can be minimized.<\/p>\n VXFrame effectively reconciles Bootstrap LESS\/CSS rules with a reusable React component architecture.<\/p>\n Many internet postings describe the component-centric advantages of React without taking any strong positions on styling and layout. Some React developers eschew CSS rules entirely, opting instead for programmatically-controlled styles embedded within the components. VXFrame fully embraces Bootstrap and avoids embedded styling.<\/p>\n Given the decision to use Bootstrap, it was necessary to devise standards and conventions to allow VXFrame components to work harmoniously with Bootstrap CSS classes. Each VXFrame component declares a set of standard CSS classes via React default properties. VXFrame components declare good defaults that facilitate typical layout behaviors and responsive design, so that in most cases the developer can ignore layout issues. When the developer needs finer-grained control, default CSS classes can be overridden via component properties.<\/p>\n VXFrame uses Flexbox (exclusively) for controlling component layout.\u00a0 Flexbox is a relatively new W3C standard which is now supported by all major browsers.<\/p>\n Flexbox rules allow developers to declare divisions of HTML that are either fixed in size or that may grow to fill available space, automatically adjusting to any device. Flexbox rules are indispensable for creating single-page apps that behave like native apps.<\/p>\n VXFrame replaces quirky Bootstrap grid float<\/strong> CSS rules with functionally-equivalent Flexbox declarations. As a result, the system is able to render complex single-page layouts declaratively, minimizing browser-specific layout anomalies.<\/p>\n VXFrame includes several built-in layout components:<\/p>\n Most VXFrame subsystems use LayoutStandard, which includes a top bar and off-canvas navigation that appears when the user presses the \u201cburger\u201d button. The off-canvas navigation fly-out uses hardware-accelerated 3D translations for smooth performance on any client, including older phones and tablets.<\/p>\n Many applications can be developed using built-in layouts. Additional layout components can be added if necessary.<\/p>\n LayoutStandard is a generalized container that houses a developer-supplied subcomponent, henceforth referred to as the content<\/em>. This layout encapsulates the content inside a transition group<\/em> to permit changes in content to be animated. VXFrame built-in animations include cross-fades, and left-to-right or right-to-left slides which are particularly important on hand-held devices.<\/p>\n VXFrame includes comprehensive support for forms<\/em>, making it easy to develop subsystems that gather information from users and store it in the database.<\/p>\n VXForm is component that can contain any number of input controls such as:<\/p>\n VXForm provides many features that are typical of web forms:<\/p>\n VXForm and its nested input components declare properties to control the validation and update process.<\/p>\n VXForm specifies global settings such as:<\/p>\n Nested input components specify additional properties that vary based on component type; for example, a VXInput control declares additional settings such as:<\/p>\n The VXFrame validation subsystem is event-driven so processing occurs whenever the user changes the value of an input component. Formatting and validation occurs immediately, while update processing can occur in two ways:<\/p>\n Traditional validation permits the emulation of legacy-style web forms, where information is gathered and then sent to the server when a button is pressed. In this mode, the user is typically offered two buttons at the bottom of the form: Save and Cancel. Save will cause the system to update the database, while Cancel will restore the form to its original state, abandoning any in-progress inputs.<\/p>\n Dynamic validation causes the system to immediately store information into the database whenever the user changes the value of an input control. This mode is ideal for collaborative applications where data needs to be dynamically shared between users.<\/p>\n VXFrame input components automatically manage their own states, so there is no need to elevate<\/em> state to higher level components. Each component maintains its internal<\/em> value (i.e., state) as an appropriate JavaScript type which varies depending on the type of control. For example, VXDate components maintain the selected date as JavaScript type Date.<\/p>\n When a component is mounted, the component state value is rendered<\/em> according to formatting<\/em> rules.\u00a0 For example, a telephone number field may be stored internally as a string of digits, yet rendered using a mask consisting of parenthesis surrounding the area code and a dash between the prefix and suffix. When data is entered by the user, mask characters are automatically stripped<\/em> from the input as specified in the formatting rules.<\/p>\n In order to function properly within the VXForm container, each input component implements a variety of standardized methods including:<\/p>\n VXFrame components automatically register themselves within their VXForm container when they are mounted. This registration process allows VXFrame to:<\/p>\n VXFrame allows multiple forms to peacefully coexist on a page when necessary.<\/p>\n VXModal components are wrappers for Bootstrap modals.<\/p>\n Traditionally, Bootstrap modals have been pre-rendered into invisible HTML that lingers in the web page document body. When the application needs to display the modal, it invokes a Bootstrap function which makes the HTML visible, while simultaneously triggering the “show” animation to bring the modal into view. When the user completes the modal, the system triggers the “hide” animation and makes the HTML invisible. In contrast, VXModal HTML is dynamically created and destroyed as needed. This approach is far superior and makes it much easier to code and manage modals, reducing cost.<\/p>\n A VXModal component typically contains a VXForm subcomponent, allowing the modal to automatically handle input validation and required fields processing.<\/p>\n VXFrame comes with three standard modal footer components:<\/p>\n Developers can easily create additional custom modal footer components if necessary.<\/p>\n VXFrame comes with an off-canvas navigation bar which is normally hidden from view, but will fly in from the left side of the screen when the user touches or clicks the \u201cburger\u201d button on the top bar:<\/p>\n Modern applications display lists of data which can be touched, clicked, dragged and dropped. Each item in the list typically has an icon or picture on the left side, with explanatory lines of text on the right side. Example:<\/p>\n In VXFrame, entity lists are represented by component EntityList. An EntityList component can any number EntityItem components, each of which contains:<\/p>\n Developers can \u201cwrap\u201d EntityList components to create specialize, reusable lists, effectively inheriting EntityList functions and behaviors. For example, the list of users shown above is represented by UserEntityList, a specialized EntityList component.<\/p>\n EntityList and EntityItem components are highly parameterized, allowing wrapper components to specify basic appearance, images, titles, decorations and tooltips. A variety of event handlers can be registered with EntityList and EntityItem to handle gestures such as selection and drag\/drop processing.<\/p>\n Entity panels are used to display and potentially edit information. Typically, an entity panel will display the information contained in a single database record, but it may also combine information from several related records. Example:<\/p>\n VXFrame allows you to develop entity panels by combining reusable subcomponents. For example, the entity panel shown above is represented by component UserDomainViewRight, which is comprised of the following subcomponents:<\/p>\n Entity panels allow the developer to quickly snap together reusable subcomponents like Lego blocks to form panels which can be used for display or edit purposes.<\/p>\n Modern web applications use sliding animations, typically triggered by user gestures, such as swiping left or right. VXFrame makes it easy to develop subsystems that boast smooth, hardware-assisted sliding animations.<\/p>\n Three VXFrame components work together to deliver sliding behaviors:<\/p>\n These components have been carefully designed to work together seamlessly to deliver an optimal experience on any desktop system or hand-held device.<\/p>\n On desktop systems, these three components create a side-by-side display, where the left-hand side presents a list of entities, and the right hand side presents the details of the currently-selected entity:<\/p>\n The utility of SlidePair is evident on a smaller screen such as a phone; in this case, SlidePair will display only the left-side panel:<\/p>\n\n
\n
React Components in Blaze Layouts<\/h3>\n
Using BlazeLayout and ReactLayout Together<\/h3>\n
Wholesale Conversion<\/h3>\n
My First Subsystem: Events<\/h3>\n
![\"\"](\"http:\/\/sotaenterprises.com\/wp-content\/uploads\/2018\/03\/events.png\")
<\/a><\/p>\nTop bar
\nBurger button
\nSystem logo
\nSystem name
\nSubsystem status indicator (many)
\nProfile photo
\nEvent selection criteria row
\nEvent type selector
\nRows selector
\nDate selector
\nEvent display body
\nEvent display row (many)
\nEvent display cell (many)<\/code><\/p><\/blockquote>\nComponents<\/h3>\n
\n
\n
Declaring HOCs<\/h3>\n
\n
Granularity<\/h3>\n
Naming Conventions<\/h3>\n
\n
\n\n
\n HOC<\/strong><\/td>\n Wrapped Component<\/strong><\/td>\n<\/tr>\n \n OffCanvasNavStandardContainer<\/td>\n OffCanvasNav<\/td>\n<\/tr>\n \n OffCanvasNavDiagContainer<\/td>\n OffCanvasNav<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n Blaze Data Contexts Versus React Properties<\/h3>\n
VXFrame<\/h3>\n
\n
\n
LESS\/CSS Rules<\/h3>\n
Flexbox<\/h3>\n
Layouts<\/h3>\n
\n
Animation<\/h3>\n
Forms<\/h3>\n
\n
\n
\n
\n
\n
Component State<\/h3>\n
\n
\n
Modals<\/h3>\n
\n
Off-Canvas Navigation<\/h3>\n
<\/a>
\nVXFrame uses off-canvas navigation instead of the standard Bootstrap menu bar, primarily to conserve screen real estate.<\/p>\nEntity Lists<\/h3>\n
<\/a><\/p>\n\n
Entity Panels<\/h3>\n
<\/a><\/p>\n\n
Slide Pairs<\/h3>\n
\n
<\/a><\/p>\n