> For the complete documentation index, see [llms.txt](https://handbook.marsbased.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://handbook.marsbased.com/our-development-guides/react-guidelines.md).

# React guidelines

We bootstrap React applications with [Vite](https://vite.dev/) for single-page apps, or a full framework like [Next.js](https://nextjs.org/) when server-side rendering or SEO matter. [Create React App](https://react.dev/), which we used on older projects, was deprecated by the React team in 2025 and should not be used for new projects.

* 1. [Do's and Don'ts](#1-dos-and-donts)
  * 1.1. [Use typescript if possible](#11-use-typescript-if-possible)
  * 1.2. [Use a generator to bootstrap the project](#12-use-a-generator-to-bootstrap-the-project)
  * 1.3. [Write functional components](#13-write-functional-components)
  * 1.4. [Use hooks for state management](#14-use-hooks-for-state-management)
  * 1.5. [Use a declarative API library](#15-use-a-declarative-api-library)
  * 1.6. [Do use function declarations](#16-do-use-function-declarations)
  * 1.7. [Do name exports](#17-do-name-exports)
  * 1.8. [Do inline type props](#18-do-inline-type-props)
* 2. [General project organization and architecture](#2-general-project-organization-and-architecture)
  * 2.1. [Project structure example](#21-project-structure-example)
  * 2.2. [References (project structure)](#22-references-project-structure)
* 3. [Description of the most common patterns used to solve common problems](#3-description-of-the-most-common-patterns-used-to-solve-common-problems)
  * 3.1. [State management](#31-state-management)
    * 3.1.1. [Local state management](#311-local-state-management)
    * 3.1.2. [Global state management](#312-global-state-management)
  * 3.2. [External services](#32-external-services)
  * 3.3. [GraphQL](#33-graphql)
  * 3.4. [REST](#34-rest)
  * 3.5. [Routing (SPA only)](#35-routing-spa-only)
    * 3.5.1. [Page vs component](#351-page-vs-component)
    * 3.5.2. [Route definitions](#352-route-definitions)
    * 3.5.3. [Router.tsx](#353-routertsx)
    * 3.5.4. [Access route parameters using hooks](#354-access-route-parameters-using-hooks)
  * 3.6. [Testing](#36-testing)
* 4. [Libraries](#4-libraries)
  * 4.1. [Recommended libraries](#41-recommended-libraries)
  * 4.2. [Other libraries we have used](#42-other-libraries-we-have-used)
  * 4.3. [Libraries worth taking a look into](#43-libraries-worth-taking-a-look-into)
  * 4.4. [References (libraries)](#44-references-libraries)
* 5. [Learning resources](#5-learning-resources)

## 1. Do's and Don'ts

### 1.1. Use typescript if possible

### 1.2. Use a generator to bootstrap the project

A project generator saves a lot of boilerplate work and provides common conventions.

Use [Vite](https://vite.dev/) to scaffold single-page apps (`npm create vite@latest -- --template react-ts`). For projects with important SEO or server-rendering requirements, use [Next.js](https://nextjs.org/) instead.

Older projects were bootstrapped with Create React App, but it's deprecated and must not be used for new projects.

### 1.3. Write functional components

Class components will be deprecated. For new components always use functions.

### 1.4. Use hooks for state management

* In general, prefer React's hooks for local stage management
* Use a library (with hooks) for global state management
* Avoid redux if possible (too complex)

See patterns (below) for examples and usages.

### 1.5. Use a declarative API library

It reduces boilerplate code a lot.

We currently use:

* REST: [TanStack Query](https://tanstack.com/query) (formerly react-query)
* GraphQL: [apollo-client](https://github.com/apollographql/apollo-client)

### 1.6. Do use function declarations

For a better readability.

```ts
// Don't declare arrow functions
const App = () => (
  <div>
    <Logo />
  </div>
);

// DO declare functions
function App() {
  return (
    <div>
      <Logo />
    </div>
  );
}
```

### 1.7. Do name exports

It allows to export multiple values and it encourages the use of the same naming.

```ts
export function LoginPage() {
  ...
}
```

### 1.8. Do inline type props

It reduces the external dependencies of the function and therefore is more easy to move or change it without errors.

```ts
// DO inline type props
export function LoginForm({user = ''}: {user: string}) {
  ...
}
```

## 2. General project organization and architecture

We follow a conventional `src/` folder structure.

For small to medium projects this is recommended:

* One entry point: `src/index.ts`
* One config file: `src/config.ts`
* One router: `src/Router.tsx`
* Declare all app routes at `src/routes.ts` (see below)
* All page components under `pages/` (can be nested to mimic routes path hierarchy)
* All non-page components under `components/` (can be nested)
* All hooks under `hooks/` (can expose Providers)
* One folder for each (external) service. For example `api/` (for rest APIs), `graphql/` for GraphQL or `auth/` for authorization service. They can include type definitions, data transformations, clients or anything related to that service and communication with it.
* One folder for locales: `locales/`
* The rest: utility functions, helpers, etc... under `lib/` (keep it clean, please)

### 2.1. Project structure example

```
src/
|- index.ts             # entry point
|- config.ts            # application configuration
|- routes.ts            # Application route definitions
|- App.tsx              # Application setup (providers)
|- Router.tsx           # Application router
|- pages/               # page components (access to router)
  |- HomePage.tsx
  |- UserListPage.tsx
  |- UserDetailPage.tsx
  |- admin/             # try to mimic the actual client urls
    |- AdminUserListPage.tsx
|- components/
  |- Layout.tsx         # Basic layout for app
  |- Spinner.tsx        # shared component
  |- Tag.tsx            # shared component
  |- posts/             # folder for specific areas, pages or sections
    |- PostForm.tsx
  |- users/
    |- UserCard.tsx
|- hooks/
   |- useUser.tsx       # hook
   |- useXXX.ts         # another kook
|- locales/
   |- type.d.ts         # Locale type definitions
   |- en-GB.ts          # locale for en-GB
|- api/                 # REST API folder (optional)
   |- index.ts
   |- types.d.ts        # API Entities type definitions
   |- client.ts         # API client
|- graphql/             # GraphQL folder (optional)
   |- types.d.ts
   |- schema.ts
|- auth/                # Authorization service (optional)
   |- types.d.ts
   |- index.ts
|- lib/                 # internal libraries aka "Everything else"
  |- randomColor.ts
|- react-app-env.d.ts   # declare missing types from npm packages
```

If using a repo for both api and client, put the above inside `client/` folder

### 2.2. References (project structure)

* Route definitions idea taken from [Redwood](https://github.com/redwoodjs/redwood) framework

## 3. Description of the most common patterns used to solve common problems

### 3.1. State management

* In general, prefer hooks over any other solution
* You-don-t-need-redux. But if so, use hooks interface

#### 3.1.1. Local state management

React hooks are enough most of the time.

#### 3.1.2. Global state management

Prefer [zustand](https://github.com/pmndrs/zustand) over React contexts or redux.

See zustand documentation.

### 3.2. External services

* Create a clean interface for each service. For example: `src/api/index.ts` (functions to send http requests to a REST API) or `src/graphql/index.ts` (queries and mutations of a GraphQL endpoint)
* Create a file with the types (models): `<service-name>/types.ts`
* Use declarative data fetching: prefer `useQuery` over `fetch` (available both in Apollo client and react-query)

### 3.3. GraphQL

We currently use [apollo-client](https://www.apollographql.com/docs/react/)

Try to generate types and code as much as possible.

In general, keep all graphql related code inside `graphql/` folder.

### 3.4. REST

* A single `src/api/index.ts` exports all possible API interactions
* Use `src/api/types.ts` to declare API entity type definitions
* Client specific functionality inside `src/api/client.ts` (like, for example)
* If Auth and API are different services, is common to have two folders (`src/auth` and `src/api`) and the API depends on authorization (JWT tokens, for example). If auth and API are in the same service, the `src/auth` folder can be omitted.

### 3.5. Routing (SPA only)

Custom routing is only required for single-page apps built with Vite (Next.js has its own routing standards and patterns).

* Use react-router-dom with hooks
* Create a route definitions file `src/routes.ts` with all route paths
* It helps to mimic the actual routes in the `/pages` folder

#### 3.5.1. Page vs component

A Page is a component that:

* It is used in `Router.tsx`
* Can access route parameters (like in: `/post/:id`)
* Lives inside `src/pages/` folder (can be nested to reflect actual url structure)

#### 3.5.2. Route definitions

It's a file to generate route paths. Advantages:

* You get an overview of all available routes on the app
* It helps to prevent errors when declaring routes
* Route completion via editor

```ts
export default {
  posts: () => `/posts`,
  post: (id: string) => `/posts/${id}`,
  admin: {
    users: () => `/admin/users`,
  },
};
```

Usage:

```tsx
import routes from "./routes";

<Link to={routes.users()}>Users</Link>;
```

#### 3.5.3. Router.tsx

Use the `routes` definitions to create the routes placeholders:

```tsx
<Router>
  <Routes>
    <Route path={routes.posts()} element={<PostsListPage />} />
    <Route path={routes.post(":id")} element={<PostPage />} />
    <Route path={routes.admin.users()} element={<AdminUsersListPage />} />
  </Routes>
</Router>
```

#### 3.5.4. Access route parameters using hooks

For a route like `/posts/:postId/comments/:commentId` we use the following code to access route params:

```tsx
const { postId, commentId } = useParams();
```

### 3.6. Testing

Use [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/), the current community standard for testing React components.

* Favour end-to-end-testing over components test
* More important to cover critical paths than general coverage
* Ensure business logic are pure functions and write unit tests for them when needed

When we write tests, we use [Cypress](https://cypress.io)

## 4. Libraries

### 4.1. Recommended libraries

* Internationalization: [react-intl](https://www.npmjs.com/package/react-intl)
* Forms: [react-hook-form](https://react-hook-form.com/)
* Global state management: [zustand](https://github.com/pmndrs/zustand)
* Server state / data fetching: [TanStack Query](https://tanstack.com/query) (formerly react-query)
* Http: [ky](https://github.com/sindresorhus/ky)
* GraphQL API: [apollo-client](https://www.apollographql.com/docs/react/)
* Routing: [react-router-dom](https://reactrouter.com/)

### 4.2. Other libraries we have used

* Styling
  * [tailwindcss](https://tailwindcss.com/)
  * [styled-components](https://styled-components.com/)
  * [xstyled](https://xstyled.dev/)
* Components
  * [antd](https://ant.design/docs/react/introduce)
* Http
  * [axios](https://github.com/axios/axios)
* Hooks:
  * [react-use](https://github.com/streamich/react-use)

### 4.3. Libraries worth taking a look into

* State management
  * [jotai](https://github.com/pmndrs/jotai)
  * [recoil](https://recoiljs.org/)
* Component library
  * [Chakra UI](https://chakra-ui.com/)

### 4.4. References (libraries)

* Blog: [Internationalize React apps done right](https://medium.com/ableneo/internationalize-react-apps-done-right-using-react-intl-library-82978dbe175e)

## 5. Learning resources

* React docs are quite good. Recommended reading: <https://react.dev/learn>
* egghead.io is one of our favourite places to learn and Kent C. Dodds is a master, so this can't fail: <https://egghead.io/courses/the-beginner-s-guide-to-reactjs>
* To learn Redux, a course at egghead by the creator of Redux itself is a MUST: <https://egghead.io/courses/getting-started-with-redux>
* This tutorial is quite good for starting with React: <https://www.fullstackreact.com/30-days-of-react/>
* <https://www.reddit.com/r/reactjs/>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://handbook.marsbased.com/our-development-guides/react-guidelines.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.