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.
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.
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.
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.
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
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
https://github.com/edx/edx-platform/blob/master/common/static/js/src/ReactRenderer.jsx
Allows rendering a react component at a given DOM ID using the version of react in edx-platform
Works today
Need to define components in webpack config (there’s some glue necessary)
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.
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.