PWA Studio Development Guiding Principles

Code Contribution Guidelines

• Code Contribution Guidelines
  • Write smaller React Components
  • Mobile first, desktop is low-priority
  • Support only the browsers targeted by the Babel build
  • Make things in Venia UI, then genericize them in Peregrine
  • Throw errors all the time

PWA Studio is a development system, not a Web app. It is a suite of tools for building Web apps and has a lot in common with integrated development environments.

Its users are developers. when you write code for PWA Studio, you are writing a user interface for the developers who use or modify the tool you have made.

Code like this has to adhere to a high standard of quality and readability, so the team has written some guidelines to help reach that standard.

Write smaller React Components

Large components should render a tree of smaller components, not a large amount of hardcoded HTML in the JSX code.

A React component should have a single purpose and a very small cyclomatic complexity.

Why?

Modularity, single-use, and composability are always best practices, but particularly in the case of ReactJS, it's hard to get too granular with your component implementations. It is definitely possible to get too granular, but that is easy to correct

Remember: The Component API is React's best asset, and it is the boundary along which we can add customization points, error handling, and additional public APIs. React is highly optimized to work with thousands of Components, and you should boldly define as many as you want.

Mobile first, desktop is low-priority

Focus your energy and implementation work entirely on mobile devices with touch screens. The Venia UX concepts are built for these devices, and designed to "fall back" to an acceptable experience on larger screens. Unlike the responsive projects of the past, you should treat mobile as the target platform, and desktop as less important.

Why?

Mobile devices are the default Internet experience of tomorrow's shoppers. Desktop computers are becoming more rare, and most eCommerce traffic in the future will be from the mobile channel.

In addition, desktop browsers can already run Progressive Web Apps. They have all the features, functionality, and performance. If a site works on a mobile device, it will work acceptably on a desktop. Therefore, the most efficient use of our time is to stay relentlessly focused on mobile devices, trusting that the desktop experience will not suffer the same kind of degradation that mobile sites do when desktops are the target. You may consider the desktop a target of graceful degradation. Fortunately, because desktops are more powerful computers, the degradation is likely to be fairly graceful.

Spend most of your time and energy with your dev tools in "mobile" mode.

Support only the browsers targeted by the Babel build

PWA Studio uses Babel to transpile modern JavaScript into a subset of the language supported by more browsers. Babel supplies a very convenient preset, babel-preset-env, which helps developers describe the desired browser coverage in very readable ways. Currently, Venia's build process targets all browsers with more than 5% market share, which you can look up using the "browserlist" utility described in the babel-preset-env documentation.

How?

The 5% rule is enforced by this code:

const presetEnvConfig = {
    targets: {
        browsers: ['> 5%']
    },
    modules: false
};

When these statistics update, Babel re-validates them when it runs.

Make things in Venia UI, then genericize them in Peregrine

When developing new UI, always do all new work in Venia UI, using whatever tools from Peregrine are helpful. At review time, the author and code reviewers can identify tools that belong in Peregrine, and migrate them.

Why?

Venia UI is the component library. Peregrine is the logic library, whose goal is to include reusable components, tools, and utilities for building storefront component.

The best way to define these requirements is by deriving them from the work we have to do on features. After writing a lot of code, developers often find themselves thinking about all the ways they wish the API was different. Peregrine is the place where developers can put that high standard for API design.

Throw errors all the time

Every failure condition in your code must raise an exception. For asynchronous cases, return a rejected promise or an emitted error event. Exceptions should be detailed, include stack traces, and describe likely causes and potential solutions.

Why?

One of the most common complaints in frontend development is silent failures. They are a natural consequence of the forgiving rendering system of the Web and the dynamic nature of JavaScript.

It is harder to write code that crashes informatively and helpfully in these conditions, but some libraries do it!

React, Redux, and Apollo are famous for their extremely helpful dev-mode console errors. We must hold ourselves to the same standard.

Make sure that every potential failure condition is covered by a descriptive error. Do not worry about the language being good; we have editors. Just make sure that you describe the error in a way a fellow developer will understand.

---

These are principles, not rules. They are meant to remind you of the vision and mission of PWA Studio, and to help your work embody that vision and mission. When you aren't sure how to design and build a system, how to review and evaluate code, or where to dedicate your time, it may help to refer back to these.