by Mirko Basic 🍀

Contributing 👷

Introduction

Greetings! 👋

Here's a short summary of the principles we're using on the projects. Everyone should stick to the agreed guidelines listed below in order to give its contribution and preserve ease the development and uniformity. Workflow and the principles will most definitely change as the project evolves so make sure to regularly check this document in order to stay up to date.

Every suggestion and critique is welcomed and appreciated and it will be considered, evaluated and potentially included in the contributing guidelines.

Thank you, the effort is much appreciated! 🙏

🍀

---

Folder Structure

├── public/
│   └── favicon.svg
├── src/
│   ├── api/
│   ├── assets/
│   ├── components/
│   ├── constants/
│   ├── context/
│   ├── features/
│   ├── helpers/
│   ├── layouts/
│   ├── lib/
│   ├── locales/
│   ├── models/
│   ├── pages/
│   ├── providers/
│   ├── routes/
│   ├── services/
│   ├── store/
│   ├── styles/
│   ├── types/
│   └── utils/
└── package.json

State Management

...

Models

Models are contained in the same-named folder. This folder contains data types definitions.

Data Fetching

Data fetching is performed with axios and react-query. Axios instance and fetching hook are located in api folder. The idea behind the fetching hooks is the encapsulation of the fetching logic thus achieving component relif, hook reusability, ease of maintanance and separation of concerns.

Fetching hook example:

import { useQuery } from 'react-query'

import { type UserProfile } from 'models'

import axiosInstance, { type Response } from './axiosInstance'

export const useGetUserProfile = (hasAccessToken: boolean) =>
    useQuery<UserProfile, Error>(
        'user-profile',
        async () => {
            const { data } = await axiosInstance.get<Response<UserProfile>>(
                '/api/user/profile'
            )

            return data.data
        },
        {
            enabled: hasAccessToken
        }
    )

Assets

All assets are contained in the assets folder, further grouped by the type in:

• fonts
• images
• svgs
• videos.

Styling

Primary way of styling the components should be with the styled-components library. Shared styles should be put in the styles folder. Styles that concern the component should be put in the same file as the component, below the component definition. Default export, if exists, goes at the end of the file.

CSS properties should be written in the following order:

• dimension
• display
• position
• box model
• text
• transform and animations
• other
• margins.

Example:

.class {
    /* Dimensions */
    width: 100%;
    min-width: 300px;
    height: 100vh;
    min-height: 500px;

    /* Display */
    display: flex;
    justify-content: center;
    align-items: center;
    flex-direction: column;

    /* Position */
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    z-index: 1;

    /* Box Model w/o Margins */
    box-sizing: border-box;
    padding: 10px;
    border: 10px solid #333;
    border-radius: 4px;
    overflow: hidden;

    /* Text */
    line-height: 1.5;
    font-size: 2rem;
    font-family: AllianceNo2;
    font-weight: 700;
    font-style: italic;
    letter-spacing: -0.01rem;
    text-align: right;

    /* Transform & Animation */
    transition: translate(-50%, -50%);
    animation: example 5s linear 2s infinite alternate;

    /* Other */
    cursor: pointer;

    /* Margins */
    margin-top: 50px;
    margin-bottom: 2rem;
}

Components

Components are located inside of the components folder and they are organized by Atomic Design methodology. This approach splits the components into:

• atoms
• moleculs
• organisms
• templates
• pages.

Atom is the smallest building unit and each subsequent group consists of several types of previous ones e.g. few atoms create a molecul, few moleculs create an organism, etc.

More about the Atomic Design methodology can be found on the link below:

https://atomicdesign.bradfrost.com/

Components should be named-exported. Every folder containing components should have a barrel file (index.ts) which will re-export all of the components contained.

Consider the following structure:

├── components/
│   ├── ComponentOne/
│   │   ├── ComponentOne.tsx
│   │   └── ComponentOneRelated.ts
│   ├── ComponentTwo/
│   │   ├── ComponentTwo.tsx
│   │   └── ComponentTwoRelated.tsx
│   ├── ComponentThree.tsx
│   └── index.ts

component folder contains three components and a barrel file. ComponentOne and ComponentTwo come with other files related to them and because of that they are contained in their own folder. Component should be same-named as the folder; the folder shouldn't contain a barrel file. The reason for this is to be able to open component file directly through searching and not to be confused by plenty of index.ts.

Barrel file of the components folder should export the component and should look like this:

export * from './ComponentOne/ComponentOne'
export * from './ComponentThree/ComponentThree'
export * from './ComponentTwo'

Providers

Folder providers keeps all necessary providers that the application needs such as React Query provider, Styled Components provider, auth provider, etc.

Utils

This folder contains utility functions e.g. functions for the usage of browser's local storage.

Locales

The locales folder contains localization files for the application.

🍀