BD-39 Technical Discovery: Upgrade Frontend Frameworks in edx-platform

Owned by Nimisha Asthagiri (Deactivated)
Last updated: Jul 20, 2021 by David Joy (Deactivated)
4 min read

Project Summary

Working on frontend code in edx-platform is extremely difficult today, as supported by the results of our recent developer satisfaction survey.  Unfortunately, there are still times when the right (or only) way to move forward and deliver value without significant overhead is to work in this codebase, rather than re-platforming an entire feature into a new micro-frontend.  Frontend code in edx-platform isn't going away completely anytime soon, and we still need to work with it, but there's significant drag inherent in doing so.

We believe we can address the root of this difficulty, and see the most positive impact for our investment, by upgrading a few of the core libraries which we use in frontend development at edX to the versions used by our micro-frontends. Specifically, Paragon, and through its required dependencies, React.

In-Scope for this Effort

  • Paragon has seen significant investment, and upgrading will improve code reuse, a11y, brandability, consistency, and developer velocity. This isn't a typo - Paragon is 14 major versions behind in edx-platform (2.6.4 -> 16.1.0).

  • React has proven to be a much faster, much more effective way for us to write frontend code, and there are a variety of features and security fixes between edx-platform's version and latest (16.1.0 -> 16.14.0). It's nearly a different framework than it was in 2017 when 16.1.0 came out, and better for it.

Out-of-Scope for this Effort

  • We are NOT upgrading Webpack with this effort, though there’s value in following to do so.

    • Webpack in edx-platform is 2.7.0.  Webpack in frontend-build is at 5.44.0.

    • There are a number of breaking changes and config schema differences through the major versions.  

Impact & Measure

What outcome is being impacted or driven by this work?

Sources of friction addressed by this effort:

  • Paragon 2.6.4 lacks a number of components, bug fixes, and quality of life improvements

  • Lack of consistent React features - need to re-learn an old style of the framework when working on edx-platform

  • All edx.org brand updates are happening in the latest Paragon, making them unavailable to edx-platform

  • Accessibility issues fixed in later versions of Paragon

  • edx-platform as a different version of Bootstrap backing Paragon, with a more limited and different set of APIs/features

  • Writing Jasmine tests in old code - access to modern Paragon/React will promote its use, letting us write more tests using a familiar framework.

How will you measure success? (Focus on singular impact  / measure when possible)

  • The following technologies will be upgraded in edx-platform, creating framework parity with our micro-frontends:

    • paragon (2.6.4 -> 13.16.4)

    • react (16.1.0 -> 16.14.0)

    • react-dom (16.1.2 -> 16.14.0)

    • prop-types (15.6.0 -> 15.7.2)

    • bootstrap (4.0.0 -> 4.6.0)

    • redux (3.7.2 -> 4.0.5)

    • redux-thunk (2.2.0 -> 2.3.0)

    • react-router-dom (5.1.2 -> 5.2.0)

  • The following dependencies will be removed from edx-platform:

    • @edx/edx-bootstrap (deprecated, unused by modern Paragon)

  • UI quality has not regressed in edx-platform and its embedded plugins (eg XBlocks, studio-frontend):

    • No new style issues

    • No new branding issues

Initial Technical Detail

  • Paragon

    • Paragon in edx-platform is version 2.6.4.  Paragon is up to version 13.13.2

    • Paragon no longer uses edx-bootstrap.

    • Paragon’s CSS classes have presumably shifted since they used to use an older version of bootstrap. 

      • Worst case, this could cause a lot of unexpected visual regressions

    • Paragon uses newer React features not in React 16.1.0 (like hooks)

    • edx-platform uses:

      • Button

      • Hyperlink

      • Icon

      • InputSelect

      • InputText

      • StatusAlert

      • Table

      • TextArea

  • React

    • React in edx-platform is version 16.1.0

    • React hooks were introduced in 16.8.0

    • React has deprecated some APIs which will likely cause a bunch of warnings in our code, if upgraded.

    • Paragon relies on hooks

  • ReactRenderer

  • Studio-Frontend

    • Question: Does upgrading React/paragon mean upgrading studio-frontend?

  • Side Note on ORA

    • ORA is an xblock that builds in its own repo.  Over the last few months, we have updated its JS implementation to build w/ webpack instead of minification

    • the existing ORA xblock ( and I assume other xblocks as well) relies on exposing a js method to the window.

    • We are in the process of supporting OpenCraft in setting up a react embedded provider within a chunk of ORA

    • The next steps in ORA are going to involve revamping individual xblock render calls and refactor the existing es5 views into react components.

Follow-up technical discovery 05-28-2021

From @Adam Butterworth (Deactivated) and @David Joy (Deactivated)

  • The following PRs should be QA’ed and merged in order.

  • We have done a good amount of digging and feel 80% confident in them.

  • Dave O. suggested this be communicated widely since if the change impacts our theme it may impact the theme of some open edX providers. In particular, he suggests checking or notifying Usman Khalid of Open Craft that this work is happening.

  • I suggest part of the acceptance criteria be a report of css file size changes for both the default (no theme) and edx.org-next them and some edXer sign off there

----

(1) Prepare edx.org-next theme for Libsass upgrade
https://github.com/edx/edx-themes/pull/737  
sandbox: http://edx-theme-libsass.sandbox.edx.org/ 

(2) Upgrade Libsass in platform
https://github.com/edx/edx-platform/pull/27683
sandbox: https://libsass-upgrade.sandbox.edx.org/ 

(3) Upgrade Bootstrap to 4.6.0
https://github.com/edx/edx-platform/pull/27751
sandbox job: https://tools-edx-jenkins.edx.org/job/sandboxes/job/CreateSandbox/39089/
will deploy to: http://bootstrap-4-6-0.sandbox.edx.org/

(4) Swap Bootstrap for Paragon and fix visual regressions
https://github.com/edx/edx-platform/pull/27771/files
sandbox job: https://tools-edx-jenkins.edx.org/job/sandboxes/job/CreateSandbox/39089/
will deploy to: http://bootstrap-paragon-swap.sandbox.edx.org/

Future: There is probably a good amount of work that could be done to optimize the sass and shrink the sizes of the outputted CSS.