Frontend Boilerplate Roadmap

[ThunderNaka]

Boilerplate Architecture

Last Update: 27/06/2024

This document outlines the current state of our frontend architecture and sets the direction for future improvements. It covers folder structure, routing, state management, component libraries, testing, forms, provider usage, and more.

Boilerplate Folder Structure

• Define top-level structure.
• Define categorization.
• Define components, their tests, styles, and hooks or subcomponents structure.
• Define regular components and reusable components colocation.
• Define hooks colocation.
• Define constants colocation
• Define data layer colocation: everything related to API calls.
• Define utils colocation
• Define styles colocation if there should be one.
• Define the page/screen's colocation, its name, and how a screen should be.

Example for top-level structure:

src/
├── assets/
├── components/
├── hooks/
├── pages/
├── services/
├── styles/
└── utils/

Components Standard

From now on, our go-to library will be Radix, which is not a component library but a primitives library; it is beneficial to have a set of reusable primitives to handle different behaviors.

This also allows us to explore our library using shadCN components derived from Radix.

Reusable Components

We should have some reusable unstyled components with their tests and documentation in Storybook.

Common:

• Typography / Text / Headings
• Button
• Badge / Chip
• Modal
• Tooltip
• Label
• Loader

Controlled and Uncontrolled variants of:

• Input
• TextArea
• Radio
• Checkbox
• Switch
• Select / Multiselect
• Datepicker
• RangePicker
• Dropdown
• FileInput (Dropzone)

Routing Standard

Currently, we are using react-router-dom to handle the routing system.

• Define Routing Library: react-router-dom
• Define routing type.
• Define routes colocation.
• Define protected routes and create examples.
• Define if modals should have a specific route or not. If that's the case, this should work with everything, including animations.
• Create a few examples of each definition or corresponding documentation.

Fetching and Remote State Handling

We mainly use axios to create API wrappers with specific configurations and react-query to cache remote data.

• Define configuration colocation in the
• Define default axios configuration.
• Define usage of interceptors with axios.
• Define usage of transformers with axios.
• Define default error handling.
• Define default error handling with Laravel.
• Define derived components colocation from remote state status. isLoading/isFetching/isPending component. isError component. Empty state component.
• Define useQuery usage and colocation and give a few examples.
• Define queryOptions default values for each critical query field.
• Define the convention for naming queryKeys and if we are going to use, for example, a query keys factory or a simple object.
• Define useMutation usage and colocation and give a few examples.
• Define prefetching usage and how and where to use it.

State Management Standard

We mainly use states, Context API, and Zustand.

• Define Context API usage:
• Establish conventions for creating and managing contexts.
• Provide examples of using Context API for state management. For global and local state. At least two examples.
• Define context provider colocation guidelines in the component tree.
• Outline the structure and organization of Zustand stores.
• Provide examples of creating and using Zustand stores for shared state.
• Define guidelines for colocating Zustand stores with related components.
• Provide examples of Context API and Zustand error handling.
• Define if we are going to test stores.
  • Provide guidelines for testing Context API and Zustand stores.
  • Offer examples of unit and integration tests for state logic.
  • Establish conventions for mocking state in tests.
• Document state management best practices in Slite.
  • Create comprehensive documentation covering all aspects of state management.
  • Include code examples, common pitfalls, and solutions.

Forms and Validation Standard

We exclusively use react-hook-forms and zod for form validation.

• Outline how to manage form state using react-hook-form.
• Define schema colocation
• Define testing practices for forms.
  • Establish guidelines for testing forms and validation logic.
  • Offer examples of unit and integration tests for forms.
• Document form creation and validation best practices in Slite.
  • Create comprehensive documentation covering most aspects of creating and validation forms.
  • Include code examples, how to debug, common pitfalls, and solutions.

Linting

Indentation

Providers

Currently, we use Stripe and Sentry in multiple projects, to name a few.

Stripe

Sentry

Google Analytics

PostHog

Frontend Testing Standard

Define at the end of the journey.

• Define our testing default scope: unit testing, integration testing, end-to-end testing, snapshots, visual testing, and a11y testing.
• Define our end-to-end testing library.
• Define our visual testing library.
• Define our integration testing library.
• Define our unit testing library.
• Define colocation for each scope.

Design System Documentation