Getting Started
Below is a collection of links to support the learning experience across our React frontend application stack. If you run into any issues, please open an issue in the Alloy Gitlab repository.
You should already have a solid knowledge of HTML, CSS, and JavaScript before using this guide.
Alloy's Purpose
- Create a consistent, modern, and delightful user experience across Vertafore products that leverage React.
- Reduce the time to deliver for both our UI designers and our developers.
React & Typescript
React
Official React JS Documentation
https://react.dev/Tutorial written by the React JS team
https://react.dev/learn/tutorial-tic-tac-toeReference
https://react.dev/reference/reactReact JS Crash Course by travesty media
https://www.youtube.com/watch?v=w7ejDZ8SWv8JavaScript to know for React
https://kentcdodds.com/blog/javascript-to-know-for-reactWhen to useMemo and useCallback
https://kentcdodds.com/blog/usememo-and-usecallbackHow to use react context effectively
https://kentcdodds.com/blog/how-to-use-react-context-effectively
Typescript
Typescript Basics
https://www.typescriptlang.org/docs/handbook/2/basic-types.htmlTypescript + React cheat sheet
https://react-typescript-cheatsheet.netlify.app/docs/basic/setup/
Routing
The current library used in Alloy and our React applications is React Router. React Router is a set of navigation components for React applications. It is also used to manage and create routing in a React application.
Forms
The current library used in Alloy and our React applications is Formik. The Formik library keeps track of values, errors, and visited fields in React forms. It works with the Yup to do form validation. Formik also handles the submission a form. Alloy also has input components that integrate our design language for form and input components.
Formik documentation
https://formik.org/docs/overviewYup documentation
https://github.com/jquense/yup
Internationalization
The current library used in our React applications is React Intl. React Intl is a set of components to manage i18n context and format dates, numbers and strings.
Styling
We use CSS-in-JS to enforce consistent styles across components. It keeps styles co-located with the components. Has a theme file where common colors, spacing, and patterns that can be imported for use in components. Finally, it injects only the exact styles needed for the render into the DOM. Auto-prefixes the styles. It minimizes the size of classnames and css delivered in production bundles.
The overall goal is that engineers should not be writing new CSS, unless they are doing so for a specific new component. Layout / Grouping / Gridding should already be handled by existing common components.
The current library used in Alloy and our React applications is react-with-styles, which wraps, Aphrodite.
React With Styles github
https://github.com/airbnb/react-with-stylesAphrodite github
https://github.com/khan/aphrodite
Testing
We want front end tests that avoid testing implementation details. Instead, front end tests should give confidence that they work for the user as intended. Tests should also be maintainable, so that components can be refactored (changes to implementation but not functionality).
We currently use react-testing-library for Unit and Integration tests. For E2E tests, we leverage Playwright.
React Testing Library
Introduction
https://testing-library.com/docs/react-testing-library/intro/Common Mistakes
https://kentcdodds.com/blog/common-mistakes-with-react-testing-libraryFoundation on Jest
https://jestjs.io/docs/getting-startedDon’t test implementation details
https://kentcdodds.com/blog/testing-implementation-detailsTutorial
https://www.robinwieruch.de/react-testing-library/
Playwright
Getting Started
https://playwright.dev/docs/introSelectors similar to testing library selectors
https://playwright.dev/docs/api/class-framelocator#frame-locator-get-by-role
Snapshot Tests
At the current time, we do not recommend using snapshot tests. They cause builds to fail when the component implementation changes and rarely catch bugs. They are not a replacement for good component level tests.
Data Fetching
React doesn't come with an opinionated way of fetching or updating data from an API.
We recommend splitting service functions into their own separate section of the application.
To handle loading and error states, as well as communicating to the services, the recommended solution is React Query, which provides an idiomatic hook for all developers to use. It comes with caching built-in and manages loading and error states. We just need to handle them. Also, they remove the need to use a state management library to handle that data.
React Query
Practical React Query Guide
https://tkdodo.eu/blog/practical-react-queryReact Query v3 docs
https://tanstack.com/query/latest/docs/framework/react/overview?from=reactQueryV3
Error Boundaries
Error boundaries are React components that catch JavaScript errors anywhere in their child component tree, log those errors, and display a fallback UI instead of crashing the entire React component tree.
The current library we recommend to use in React applications is: react-error-boundary.
For more information on how to use error boundaries, please refer to this Blog Post.
Floating / Overlay UIs
Alloy uses a library called `@floating-ui/react`. This library is a set of components to manage floating / overlay UI elements in React applications.