Venia Code Requirements

Venia Code Requirements

We are committed to holding Venia code to an exceptionally high standard. Our authors and volunteer contributors have held to this standard, and we believe anyone can. There are a few rules to remember, but they are not small nor arbitrary. On this project, we do not waste time debating semicolons.

Code Purpose

Venia code and any contribution you make must serve the following purposes:

Solve a problem

All code changes must make the Venia storefront a better eCommerce site and a better PWA in a measurable way. An eCommerce site must have a number of complex, yet user-friendly workflows.

Progressive Web Apps serve a number of difficult use cases and conditions. An eCommerce PWA therefore has a lot of problems to solve.

A PR should solve a problem that Venia experiences today. We can anticipate future problems that emerge, but we have to solve current problems before we admit code changes that only pertain to future scaling or architectural concerns.

Follow the Magento Commerce 2 feature set

The Venia storefront is a showcase of the new Magento 2 storefront experience. Each component, action, and module should help to express a Magento 2 feature. Venia should ultimately support all Magento 2 core storefront functionality, including bundled extensions.

PRs which implement any functionality which Magento already exposes in its GraphQL or REST APIs should use those APIs.

Be a teaching tool

As a contributor to Venia, you are writing code that a big community of partners and developers will read and learn from. Therefore, code you write should be readable.

We keep to this rule through code reviews and case-by-case opinions, rather than with excessive code linting or rules about comments.

Code Quality

Venia must be high-quality code. To keep our code quality high, your contribution should:

• Run reliably in all supported environments
• Be consistent in style
• Easy to refactor
• Be covered by tests

Run in supported browsers

In our Definition of Quality, we define which browsers Venia must support. Any code changes must work reliably in all of these browsers, or fall back to an acceptable graceful degradation experience.

Adhere to the style of the project

Don't worry about semicolons, carriage returns, or underscores. In our definition, the "style" of the project is the overall architecture of PWA Studio as described in our core documentation.

Some general rules to follow include, but are not limited to:

• For contributions to the current release branch, use only Magento features in the current release candidate or version.
• Whenever possible, use the Magento GraphQL API to obtain data. The Magento REST API is currently in use for those areas GraphQL does not cover in 2.3.0, but it is considered to be temporary. The project's goal is to use only GraphQL for data.
• Whenever possible, use Peregrine hooks to request Magento GraphQL or REST data. Other call styles will be evaluated case-by-case.
• Use the appropriate Peregrine hooks to get read and write access to the global application state.
• The global state data can be grouped by features, such as cart, user, and order. Use the appropriate Peregrine hook to gain access to a specific slice of the global state.
• Always use CSS Modules for styling components. Always use the classify higher-order component to export the generated CSS classes on components.

Here are some examples of Venia code contributions that would violate project style:

• Statically importing large libraries

• Using DOM nodes directly where React elements would work

• Writing style outside of the CSS Modules system

• Writing style that does not resemble the rest of the style in the project. For example:

  • Writing complex selectors instead of plain class selectors
  • Hardcoding common value instead of using CSS Variables
  • Using arbitrary pixel widths instead of rem and fr
  • Using "CSS hacks" for older browsers

• Causing side effects at module load time (except in src/index.js)

• Adding stateful shared globals anywhere but in the Redux store (including parent component state)

• Adding server-side code to Venia outside the UPWARD file and template files

As the project matures, this definition will update to be more detailed, instead of a list of "do's and don'ts". In the meantime, code reviewers should be vigilant in maintaining the essential structure of the Venia project.

Make it easy to refactor

If your functionality can be a React function component, make it a React function component. React components have a simple, consistent API.

If your functionality changes state, use the appropriate Peregrine hooks. If your functionality is shared by many components, consider writing a Peregrine hook instead of a general-purpose utility.

And finally, if your code is more generally useful to PWAs, and is not specific to Venia UX or Magento workflow, consider adding it to Peregrine!

Write tests

We test with Jest. We test React components with Enzyme. Code contributions should include tests. New code should be 100% covered, or if not 100% covered, should include comments to disable Istanbul coverage and explain why the test cannot reach this branch of code.