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 bit.

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 🛠

React, and Redux, and Javascript, oh my!

Once you’ve gathered your requirements, it’s time to start coding! 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.

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

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!

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 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 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

How to contribute to Paragon

Status
colour Yellow title WIP

How to translate strings

Internationalization (i18n) is an important piece of the development process. Correctly formatting our strings for translation is crucial to avoid jeopardizing our user experience in different languages.

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/

Test 🔍

Status
colour Yellow title WIP

Deploy 🚀

Status
colour Yellow title WIP