Enterprise Frontend/React - Best Practices (DRAFT)


Overview
This document outlines best practices for writing/developing enterprise Frontend/React components, libraries, and applications at scale. Please make every attempt to follow these guidelines as closely as possible.
Objectives
Outline best practices, guidelines, plugins, and tools that can be adopted, streamlined and integrated into React development for use across all platform teams
Understand what it would take to implement these guides and tools
Document and present guidelines to managers for approval.
Work with teams to implement those guidelines.
GOALS
Improve product development, delivery, and iteration process
Provide consistent user experience
Improve application performance
Expected Outcomes
Reduced developer onboarding time
Improved developer velocity to ensure product features are delivered Sprint
Improved code quality, reduction bugs and technical debt
Improved application performance, standards, and accessibility
Overview (Frontend Guidelines)
General
All applications, pages, components must have a consistent visual an functional user experience
Code function, format and structure should be consistent, no matter the number of contributors.
Always strive to maintain standards and best practices, but not at the expense of practicality. Use the least amount of markup with the fewest intricacies whenever possible.
Code should be easily understandable. complex code makes maintenance and debugging difficult and expensive.
Code reuse saves time, write reusable code follow the DRY (don’t repeat yourself) code principle whenever possible. DRY code is easy to maintain, refactor and manage.
Always follow recommended naming conventions attributes, classes, functions, filenames etc.
Always write semantic and compliant HTML5 markup; semantic markup including proper page landmarks (header, section, footer, main.)
Ensure the components, application and sites are accessible to all users by following guidelines
Ensure that all markup adhere to ARIA/WAI-ARIA Authoring guidelines and best practices ensuring that content can be accessed regardless of any user's impairments
All components and widgets should follow the pattern guidelines outlined by
Use well documented/supported libraries or vanilla code where possible. Don't include unnecessary server-side code, libraries, frameworks, preprocessors, and other such dependencies — they can make the code less portable, and harder to run and understand.
When using external libraries please ensure that they are in active development, have strong developer community support, are well documented and provide a tangible benefit to the project
Please ensure that all imported libraries are updated and monitored for security vulnerabilities
Document your code whenever you can as it allows the team(s) to better understand code functions and usage.
Writing self-documenting code can help keep our codebase lite and readable—write descriptive classes, functions, variables names, etc. Use code comments sparingly and as an alternative to self-documenting code—this mix will help keep code clutter free while allowing other team members to better read, implement and support our codebase(s).
Provide additional documentation with usage/code examples whenever possible
HTML Guidelines
Use HTML semantic tags, avoid nested div’s (div soup) use semantic html to write you markup.
Define your page structure using the correct sections and outlines
Reduce the use Html tables elements, table elements are not responsive, and it attached horizontal scrollbar on small devices, please use flexbox/css-grids whenever supported to reduce dependency on HTML tables
Variable names, HTML class names, HTML id names should be consistent across the project.
Refrain from creating ids to HTML elements when requirement is just to style HTML elements. Ids should be unique throughout the HTML page. So please check for the id-name if it is already assigned to some other HTML element.
Please refer to the following link(s) for a more detailed guide on HTML best practices
CSS Guidelines
Use Global scss/css styles at all times, do not inline styles
Use Dart Sass (sass) for writing SCSS files as
When grouping selectors, keep individual selectors to a single line.
Include one space before the opening brace of declaration blocks for legibility.
Place closing braces of declaration blocks on a new line.
End all declarations with a semi-colon. The last declaration's is optional, but your code is more error prone without it.
Lowercase all hex values, e.g., #fff. Lowercase letters are much easier to discern when scanning a document as they tend to have more unique shapes.
Quote attribute values in selectors, e.g., input[type="text"]. , and it’s a good practice for consistency.
Avoid specifying units for zero values, e.g., margin: 0; instead of margin: 0px;.
When import CSS/SCSS files please use the @use as the @import rule is deprecated
The Sass team discourages the continued use of the @import rule. Sass will over the next few years, and eventually remove it from the language entirely. Prefer the instead. (Note that only Dart Sass currently supports @use. Users of other implementations must use the @import rule instead.)
Don’t use @import for external css resources as it is slower, adds extra page requests, and can cause other unforeseen problems. Avoid them and instead opt for an alternate approach.
Place media queries as close to their relevant rule sets whenever possible. Don't bundle them all in a separate stylesheet or at the end of the document. Doing so only makes it easier for folks to miss them in the future.
The foundations of a solid CSS architecture can uphold the project as it begins to scale and grow. If these foundations have not been constructed properly, your project could likely fall over in the future.
CSS will not likely break the system as a JavaScript error might. However, it can create different issues that make working on the project very difficult. If you have a team of engineers who are not confident in adding or changing CSS in the project, they are more likely to introduce bugs. These bugs will find their way to your end-users, and the project’s success may be affected because of this.
Resources / Tools
JavaScript
Adopt JavaScript EcmaScript6 best practices. Eg. Use ‘let’ over ‘var’. Use arrow functions. Specify data types.
Only insert JavaScript links in head of the document or above the closing body tag, inline <script/> tags will be rejected.
Use async or defer when loading JavaScript files in the header of your page.
JQUERY, is/or probably was one of the most popular/useful JS libraries ever—however most of JQUERY functionality has been replaced by native JavaScript functions, as a results framework like bootstrap are replacing jQuery with native (vanilla) JavaScript. . Avoid using JQuery whenever possible
Do not mix frameworks like jQuery with reactive applications like Angular and Vue.js or React it is not necessary, please use framework API functions/features or vanilla JavaScript.
Check licensing and vulnerabilities for any JavaScript library or utility before use.
Please ensure that all imported javascript libraries are updated and monitored for security vulnerabilities
Guidelines Deep Dive - React Development
(TDB)
Code Examples
(TBD)
Resources

Framework Guidelines
React
React can change how you think about the designs you look at and the apps you build. Where once you might have seen a forest, after working with React, you will appreciate the individual trees. React makes it easier to think in design systems and UI states.
General Guidelines
Start with a static mock of your component whenever possible as this helps us identify key features and gives structure to your application.
Break The UI Into A Component Hierarchy, identifying components, common elements and required functionality.
Use Functional Components instead of classes — Functional components are the stateless component that simply accepts data and display the output in some form, while Class components are stateful components that implement logic and state.
To make components reusable, break the larger component into smaller ones. That means instead of putting multiple functionalities in one component create one component that will be responsible for single functionality, the principle is called as “single responsibility principle”.
To minimize the component complexity it is always a good practice to isolate your stateful data-loading logic from the rendering stateless logic.
Avoid using Indexes as a Key Props According to React document, Key props help react to identify which item has been changed, added, or removed. Therefore, the key should be given to the element inside the array to give the elements a stable identity.
A properly maintained folder and file structure help you to understand project flow and simplify code maintenance and extraction to any other project.
Always follow naming conventions. Following naming conventions ensures users know how to name digital assets so that they will remain consistent and correct.
Testing ensures code integrity. Therefore it is good practice to create a Test directory within your component’s directory to perform all the required tests and ensure that the addition of new code will not break the existing functionality.
Have an understanding of Composition vs Inheritance in React and how it affects development.
Guidelines Deep Dive - React Development

Code Examples


AEM
TBA (Add guidelines for AEM best practices)
TEAMS

“Frontend Engineers work closely with the UX/UI, Development and Product teams to design, develop, and build optimized user EXPERIENCES for web applications.”
Responsibilities (core)
Work closely with the UX/UI, Development and Product teams to design, develop, and build optimized user EXPERIENCES for web applications.
Implement robust data visualizations and user interfaces that delight our customers
Write reliable, maintainable code by utilizing design patterns and refactoring techniques.
Craft performant high-quality features while ensuring quality through automated testing (unit, integration, e2e, and exploratory)
Ensure the product is accessible for all users by following WCAG 2.1 guidelines
Ensure that applications are responsive accross device
(Modern Frontend Engineering Roles)
UI Development
Works closely with the UI/UX to create user interfaces that reflect the client’s requirements and the design team’s intent.
Proficient at responsive modular/scalable CSS/SCSS, UI frameworks, design systems, progressive enhancement & accessibility, animation.
Understanding of the (UI/UX) process (optional)
Application Development
Focuses on function, interaction, reactivity, and usability of user interfaces
Proficient with JavaScript frameworks, JavaScript preprocessors, code quality, process automation, routing, testing
Data access, integration and management, auth, state, etc
Frontend Ops (operations)
Application development
Provides platform support for the team at all points of the development process
Works with build tools, VCS, deployment, automation, performance: (app, tests, builds, deploys), monitoring errors/logs, and Application stability
Streamlining and management of Frontend operations
Repository Management
Package management
Front End Specialist/Lead (hybrid)
UI Development
Application development
Frontend Ops (operations)
Version Control

General Guidelines
Committing often keeps your commits small and, again, helps you commit only related changes. Moreover, it allows you to share your code more frequently with others. That way it’s easier for everyone to integrate changes regularly and avoid having merge conflicts. Having few large commits and sharing them rarely, in contrast, makes it hard to solve conflicts.
You should only commit code when it’s completed. This doesn’t mean you have to complete a whole, large feature before committing. Quite the contrary: split the feature’s implementation into logical chunks and remember to commit early and often. But don’t commit just to have something in the repository before leaving the office at the end of the day. If you’re tempted to commit just because you need a clean working copy (to check out a branch, pull in changes, etc.) consider using Git’s “Stash” feature instead.
Resist the temptation to commit something that you “think” is completed. Test it thoroughly to make sure it really is completed and has no side effects (as far as one can tell). While committing half-baked things in your local repository only requires you to forgive yourself, having your code tested is even more important when it comes to pushing / sharing your code with others
Begin your message with a short summary of your changes (up to 50 characters as a guideline). Separate it from the following body by including a blank line. The body of your message should provide detailed answers to the following questions: What was the motivation for the change? How does it differ from the previous implementation? Use the imperative, present tense („change“, not „changed“ or „changes“) to be consistent with generated messages from commands like git merge.
Having your files backed up on a remote server is a nice side effect of having a version control system. But you should not use your VCS like it was a backup system. When doing version control, you should pay attention to committing semantically (see “related changes”) – you shouldn’t just cram in files.
Branching is one of Git’s most powerful features – and this is not by accident: quick and easy branching was a central requirement from day one. Branches are the perfect tool to help you avoid mixing up different lines of development. You should use branches extensively in your development workflows: for new features, bug fixes, ideas…
Follow your teams agreed workflow and branching strategy

Code reviews
Code reviews play an important role in the development process helping to reduce bugs, ensuring standards and improving the overall health of the codebase. Please ensure that code you thoroughly review pull requests (PR) ensuring code quality and before approving. Do not rubber-stamp PR approvals for any reason.
Using welcoming and inclusive language
Being respectful of differing viewpoints and experiences
Gracefully accepting constructive criticism
Focusing on what is best for the team/org
Showing empathy towards other team members
Technical facts and data overrule opinions and personal preferences.
Reference the code style-guide whenever possible to help developers improve the quality of code in a PR
Leave comments that help a developer learn something new. Sharing knowledge is part of improving the code health of a system over time.

Your link was not successfully embedded. Please try again with a different URL.
Accessibility
What is Web Accessibility?
Web accessibility refers to the inclusive practice of removing barriers that prevent interaction with, or access to websites, by people with disabilities. When sites are correctly designed, developed and edited, all users have equal access to information and functionality. - Wikipedia

Performance (WIP)
When you're building a modern web experience, it's important to measure, optimize, and monitor if you're to get fast and stay fast. Performance plays a significant role in the success of any online venture, as high performing sites engage and retain users better than poorly performing ones. Sites should focus on optimizing for user-centric happiness metrics.
General guidelines
TBD
Resources

Security (WIP)
N/A

Timeline/Roadmap
FE/REACT Timeline
3
Search
General guidelines
HTML, CSS, JS Guidelines
React Guidelines
Code reviews, Accessibility, Performance Guidelined
RFC (Request for comments)
Security Best Practices (FE)
FE Team roles
Web/Online (SharePoint Site)
Implementation (FE Teams)
Oct 2021
Nov 2021
Dec 2021
Jan 2022
Feb 2022
General guidelines
HTML, CSS, JS Guidelines
React Guidelines
Code reviews, Accessibility, Performance Guidelined
RFC (Request for comments)
Security Best Practices (FE)
FE Team roles
Web/Online (SharePoint Site)
Implementation (FE Teams)

Add feature
Roadmap
3
Search
Feature
Start Date
End date
Effort
Proprity
1
General guidelines
10/4/2021
11/29/2021
Small 🐜
Medium
2
HTML, CSS, JS Guidelines
10/25/2021
12/20/2021
Small 🐜
High
3
React Guidelines
11/1/2021
1/3/2022
Medium 🌴
High
4
Code reviews, Accessibility, Performance Guidelined
11/29/2021
1/17/2022
Medium 🌴
Medium
5
RFC (Request for comments)
1/5/2022
1/22/2022
Small 🐜
High
6
Security Best Practices (FE)
1/10/2022
1/31/2022
Medium 🌴
High
7
FE Team roles
12/27/2021
1/6/2022
Medium 🌴
Medium
8
Web/Online (SharePoint Site)
1/3/2022
1/31/2022
Medium 🌴
Low
9
Implementation (FE Teams)
12/27/2021
1/27/2022
Large ⛰
High
There are no rows in this table

Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.