OEP-11: Front End Technology Standards¶

Technology Selection¶

1. Server-side content should be rendered with Django Templates

   Rationale: There are many template languages available for Django, but the simplest option is to use the built-in Django template engine. The Open edX codebase has a mixture of Django and Mako templates, but the former are easier to reason about because they don’t support arbitrary code evaluation. See Reasons for rejecting Mako for a more detailed explanation.

   Exception: Mako templates can continue to be used within edx-platform for consistency with the existing code base. This is because the base templates and theming support are all provided via Mako, so it is too much to expect a new feature to be implemented with a different framework. There is much desire to replace Mako within edx-platform so this exception may eventually be removed.

2. Target the latest standardised JavaScript version (ECMA-262)

   Rationale: edX JavaScript should be written consistent with the latest ECMA-262 specification in order to ensure future support, the largest community and the availability of modern features. To support this syntax in older browsers, use Babel. Babel may also be configured to add syntax extensions widely adopted by the community of our recommended framework (e.g., JSX).

   Exception: Much of edX’s existing front end code is written conformant to the version of ECMA-262 released in 2009 (ES5). Files written in ES5 should be gradually converted to the newer standard as new development in those feature areas requires.

   Note: edX previously used CoffeeScript, but its use has now been deprecated. Community interest in TypeScript has also grown, but it and other languages that do not follow the ECMA-262 spec should not be used. See Reasons for rejecting CoffeeScript and Reasons for rejecting TypeScript for more detail.

3. JavaScript libraries should be installed via npm

   Rationale: It is important that JavaScript libraries are kept up-to-date, and one key component is to make it as simple as possible to perform upgrades. Projects that use npm maintain all of their library requirements in a single package.json file, which can be easily changed as the versions change.

4. JavaScript code should follow the edX ESLint configuration

   Rationale: In order to standardize and enforce Open edX’s JavaScript coding style across multiple codebases, edX has published an ESLint configuration that provides an enforceable specification. The edX ESLint Config is made available as an npm package that can be installed into any Open edX package.

   Exception: The edX ESLint Config for ES5 may be used where ES5 is in use. Both configs may be used in the same codebase through the use of ESLint configuration cascading.

5. Use React and Redux when building new client-side applications

   Rationale: React should be used for building new UIs, as it is widely adopted by the community and strikes a balance between flexibility and feature richness. For state management of complex client-side interactions, Redux should be used. This library was chosen because it sees strong use in the React community, but is also flexible enough to be used in situations where a hybrid React/Backbone architecture exists.

   See React at edX for more details on the evaluation process that led to this technology selection. Other modern frameworks considered for use included Polymer and Angular. See Reasons for rejecting Angular and Reasons for rejecting Polymer for an exploration of why these alternatives do not work as well as React for edX.

   Exception: When building new applications within edx-platform, it is currently acceptable to use Backbone. Backbone is a somewhat old technology in the JavaScript world and has seen a rapid drop off in usage within the community. The plan is to incrementally adopt React within edx-platform as it can interoperate cleanly with Backbone. More documentation on this plan can be found in Modernizing the edX front end stack.

6. JavaScript should be bundled using Webpack

   Rationale: Webpack is the tool of choice for code optimization and bundling, as it is widely used throughout the industry, and because it seamlessly handles modern code bases as well as all of the older technologies used by edX, such as AMD Modules. Webpack should be implemented to handle as much of the “asset pipeline” as possible, rather than passing this responsibility on to Django.

7. JavaScript dependencies should be managed with ES2015 Modules

   Rationale: JavaScript module systems allow front end code to specify its dependencies and be grouped into bundles that minimize the assets needed to provide page functionality. The most prevalent module syntax is currently ES2015 Modules, which should be adopted everywhere edX code is written to the ES2015 spec or later.

   Exception: Much of edX’s existing (ES5) JavaScript uses the older AMD Modules syntax for modules. AMD Modules are interoperable with ES2015 Modules if Webpack is used for bundling, so AMD is an acceptable module definition if the code must remain ES5.

8. CSS should be generated using Sass

   Rationale: Sass’s SCSS syntax is an extension of CSS that adds power and elegance to the basic language. It makes the maintenance of large CSS files more manageable though the ability to use variables, mixins, imports and more. In particular, it makes theming possible with the ability to override variables that define colors, fonts etc.

   You can find out more about Sass in the official Sass documentation.