This handbook is meant to provide an overview of how we develop frontend features at edX. We’ll guide you through our four main phases of frontend development and provide checklists, tips, and tutorials in areas that you should aim to strengthen your skills in over time.

Pre-Development 📝

What is pre-development? Pre-development is everything that goes on before you start coding. The things that happen in pre-development are mostly out of your hands, but as an engineer, there are things you should be aware of to make the development process more smooth.

The two main pieces of pre-development are product definition and design. In product definition, your Product Manager will define what is to be built (along with why/when/how). In product design, your Designer will provide a feature mockup through Figma. This is where your awareness as an engineer is important.

Pre-development checklist

When you’re given a mockup by a Designer, consider the items in the following checklist. If anything is missing, you’ll want to ask your Designer for clarity before starting development.

This list is a starting point to make sure you have what you need to effectively develop your feature. We encourage you to collaborate with a Designer in answering these questions as early in the process as possible. If you can think of more common questions, please add to the checklist above.

What is Paragon?

Paragon is our open-source component library that reflects our design system. Using components (and other styling elements) from Paragon allows us to maintain consistency across our different platforms.

If you’re familiar with Bootstrap, Material UI, Semantic UI, or similar UI frameworks, you’ll get the hang of Paragon in no time! Paragon is comprised of components and styling utility classes that are based on React-Bootstrap (https://react-bootstrap.github.io/ ) under the hood.

Additionally, Paragon is a theme-ready library, so anyone using the library is able to override the default colors and typography with their own theme. We do this at edX to override the Open edX styling with our own branding through https://github.com/edx/brand-edx.org, but we’ll get into the specifics of this in a bitthe Deploy section of this handbook.

How do we use Figma?

Figma is a really powerful design tool that allows designers to create mockups using our design system elements. Currently, our entire Paragon Design System is represented in Figma. This allows designers to pull components into their Figma mockups without having to re-invent the wheel.

When you receive a design in Figma, it may be overwhelming to understand how to pull information from it and translate the styling to Paragon or CSS. Fortunately, we have a recorded workshop that aims to walk you through this process. We’ll talk a bit more about the do’s and don’ts of CSS in the following section.

Develop 🛠

Once you’ve gathered your requirements, it’s time to start coding! Most frontend Frontend features will usually consist of most, if not all, of the following steps:

1. Using JavaScript, React, and Redux to build components,

2. styling using SASSSass/CSS and Paragon,

3. following accessibility (a11y) best practices,

4. and properly implementing internationalization (i18n).

React, and Redux, and Javascript, oh my!

React: All of our microfrontends (MFEs) are written using ReactJS. If you’re new to React, take a look at the following resources to familiarize yourself with the framework and best practices.

• https://reactjs.org/docs/getting-started.html

• https://reactjs.org/tutorial/tutorial.html

• Beta React.js Tutorial: https://beta.reactjs.org/learn

Redux: For state management in React, we use Redux. If you’re new to state management, the Redux documentation is a good place to start to understand how to think in Redux: https://redux.js.org/understanding/thinking-in-redux/motivation.

Understanding and working with Redux can be overwhelming at first, so take time to familiarize yourself with the repo you’re working in. Some repos, like frontend-app-learning, have ADRs (architecture decision records) that describe the structure of the code. This ADR from frontend-app-learning talks about the structure of its model store which uses Redux. Try finding an ADR for the repo you’re working in, and when in doubt, ask a team member or the frontend community in Slack!

Javascript: If you’re new to JavaScript, or you’re looking to improve your mental model, this https://justjavascript.com/ course may be a good resource for you. In Just JavaScript, Dan Abramov breaks down core JavaScript concepts to fill in gaps and enhance your understanding of JavaScript’s underlying functionality.

Styling using SASS/CSS and Paragon

CSS Do’s and Don’ts

In terms of styling, it may take some time to get used to translating Figma designs to code. While you’re styling your components, you’ll want to ask yourself, “Can I achieve this styling using Paragon/Bootstrap utility classes?” We generally want to avoid building custom CSS solutions for things that can be achieved using our design system utility classes.

Leaning on our design system allows us to avoid creating tech debt because our branding can remain centralized. This way, if we decide to update a major color like $brand, we only have to update it in our theme files, rather than chasing it down and replacing it in a number of different CSS files in across different repos.

Here are a few examples of CSS do’s and don’ts:

When in doubt, search for what you’re attempting to style in Paragon’s list of CSS utility classes before creating custom CSS.

How to contribute to Paragon

Status
colour Yellow title WIP

Accessibility (a11y)

Hopefully in your time as an engineer you’ve been introduced to the concept of web accessibility (a11y) and its importance. A11y at edX is addressed throughout many pieces of the feature creation process. We capture best practices in our Paragon Design System, we implement our design system components with a11y in mind, and as engineers, we aim to advocate for a11y at every step of the frontend development lifecycle. We covered some concepts to be aware of in the pre-development phase, now let’s get into how a11y plays a role in the development phase.

As an engineer in the development phase, there’s plenty to address in order to be following a11y best practices. This section can’t possibly cover everything, which is why it’s important to familiarize yourself with a11y best practices. We aim to follow https://www.w3.org/TR/WCAG22/. This long list of guidelines may seem overwhelming at first, but it’s a pretty comprehensive list of what you’re expected to have in your tool belt as a frontend developer.

Fortunately, there are ways to automate verifying your code’s a11y so that you don’t have to memorize all of these guidelines (unless you want to!). We’ll get into automated a11y testing in the Testing section of this handbook. The baseline expectation is that you’re aware of a11y, and that you ask questions if you’re unsure about whether your code is accessible or even how to approach building something in an accessible way. Ask your questions in the #accessibility Slack channel (available in both edX and Open edX Slack workspaces).

Internationalization (i18n)

edX uses a service called Transifex that sources translations from a volunteer based community and populates our repos with those translations. Your job as an engineer is to prepare all of the strings you use to be translated properly. This means using proper syntax and providing adequate context for the translators. Correctly formatting our strings for translation is crucial to avoid jeopardizing our user experience in different languages. For more on i18n, visit https://openedx.atlassian.net/wiki/spaces/LOC/overview.

General resources and tutorials

React tutorials

• https://reactjs.org/docs/getting-started.html

• https://reactjs.org/tutorial/tutorial.html

• Beta React.js Tutorial: https://beta.reactjs.org/learn

• React Component Design Tips & Tricks

CSS/Sass tutorials

• http://sass-lang.com/guide

• http://caniuse.com/

Javascript tutorials

• https://justjavascript.com/

Accessibility

• …

Test 🔍

Status
colour Yellow title WIP

Writing Tests Using Jest

Accessibility Testing

https://openedx.atlassian.net/wiki/spaces/A11Y/overview#Desktop

Manual Testing

Deploy 🚀

Status
colour Yellow title WIP

Creating a Pull Request

use conventional commit messages

include screenshots and/or videos

How to apply brand theming locally

When you’re developing in an MFE, all of the pages will be styled in the default Open edX theme. In order to apply a theme locally (for example, https://github.com/edx/brand-edx.org ), follow these steps: https://github.com/openedx/frontend-build#local-module-configuration-for-webpack