Revised contributing.md, edited docs (#1951)
* Added Overview page * Revised Getting Started page * Minor revision * Edited readme, minor modifications to docs * Removed sweep.yaml, .devcontainer, .ergomake * Moved security.md to .github, added contributing.md * changes as per code review * updated contributing.md * fixed broken links & added missing links in doc, improved structure * fixed link in wsl setup * fixed server link, added https cloning in yarn-setup
This commit is contained in:
Nimra Ahmed
@@ -1,10 +1,11 @@
|
||||
---
|
||||
title: Best Practices
|
||||
sidebar_position: 3
|
||||
sidebar_custom_props:
|
||||
icon: TbChecklist
|
||||
---
|
||||
|
||||
# Best practices
|
||||
This document outlines the best practices you should follow when working on the frontend.
|
||||
|
||||
## State management
|
||||
|
||||
@@ -14,7 +15,7 @@ We use React and Recoil for state management.
|
||||
|
||||
We recommend that you create as many atoms as you need to store your state.
|
||||
|
||||
Rule of thumb : It's better to be using too many atoms than trying to be too concise with props drilling.
|
||||
**Rule of thumb:** It's better to use additional atoms than trying to be too concise with props drilling.
|
||||
|
||||
```tsx
|
||||
export const myAtomState = atom({
|
||||
@@ -50,13 +51,13 @@ Re-renders can be hard to manage in React.
|
||||
|
||||
We provide you with some rules that we follow to avoid unnecessary re-renders.
|
||||
|
||||
Keep in mind that re-renders can **always** be avoided by understanding the cause of the re-render.
|
||||
Keep in mind that re-renders can **always** be avoided by understanding their cause.
|
||||
|
||||
### Work at the root level
|
||||
|
||||
We made it easy for you to avoid re-renders in new features by taking care of eliminating them at the root level.
|
||||
|
||||
There's only one `useEffect` in the sidecar component `PageChangeEffect` that is holding all the logic that should be executed on a page change.
|
||||
There's only one `useEffect` in the sidecar component `PageChangeEffect` that holds all the logic that should be executed on a page change.
|
||||
|
||||
That way you know that there's only one place that can trigger a re-render.
|
||||
|
||||
@@ -64,13 +65,13 @@ That way you know that there's only one place that can trigger a re-render.
|
||||
|
||||
Re-renders are often caused by unnecessary `useEffect`.
|
||||
|
||||
You should think whether the useEffect is really needed, or if you can move the logic in a event handler function.
|
||||
You should think whether the `useEffect` is really needed, or if you can move the logic in a event handler function.
|
||||
|
||||
You'll find it generally easy to move the logic in a `handleClick` or `handleChange` function.
|
||||
|
||||
You can also find them in libraries like Apollo : `onCompleted`, `onError`, etc.
|
||||
You can also find them in libraries like Apollo: `onCompleted`, `onError`, etc.
|
||||
|
||||
### Use a sibling component to extract useEffect or data fetching logic
|
||||
### Use a sibling component to extract `useEffect` or data fetching logic
|
||||
|
||||
If you feel like you need to add a `useEffect` in your root component, you should consider extracting it in a sidecar component.
|
||||
|
||||
@@ -137,7 +138,7 @@ They are especially useful when you need to store a list of items.
|
||||
|
||||
### You shouldn't use `React.memo(MyComponent)`
|
||||
|
||||
We do not recommend `React.memo()` usage because it does not solve the cause of the re-render, but instead breaks the re-render chain, which can lead to unexpected behavior and make the code really hard to refactor.
|
||||
We do not recommend using `React.memo()` because it does not solve the cause of the re-render, but instead breaks the re-render chain, which can lead to unexpected behavior and make the code really hard to refactor.
|
||||
|
||||
### Limit `useCallback` or `useMemo` usage
|
||||
|
||||
@@ -155,6 +156,8 @@ They are often not necessary and will make the code harder to read and maintain
|
||||
|
||||
4. **Professionalism**: End users or clients checking the console and seeing a myriad of log statements might question the code's quality and polish.
|
||||
|
||||
Make sure you remove all `console.logs` before pushing the code to production.
|
||||
|
||||
## Naming
|
||||
|
||||
### Variable Naming
|
||||
@@ -181,7 +184,7 @@ const [email, setEmail] = useState('');
|
||||
|
||||
### Event handlers
|
||||
|
||||
Event handler names should start with `handle`, `on` is a prefix used to name events in components props
|
||||
Event handler names should start with `handle`, while `on` is a prefix used to name events in components props
|
||||
|
||||
```tsx
|
||||
// ❌ Bad
|
||||
@@ -201,9 +204,9 @@ const handleEmailChange = (val: string) => {
|
||||
|
||||
Avoid supplying the default value for an optional prop, as it generally doesn’t contribute significantly.
|
||||
|
||||
EXAMPLE
|
||||
**EXAMPLE**
|
||||
|
||||
Assume, we have the `EmailField` component defined below
|
||||
Assume, we have the `EmailField` component defined below:
|
||||
|
||||
```tsx
|
||||
type EmailFieldProps = {
|
||||
@@ -216,7 +219,7 @@ const EmailField = ({ value, disabled = false }: EmailFieldProps) => (
|
||||
);
|
||||
```
|
||||
|
||||
USAGE
|
||||
**USAGE**
|
||||
|
||||
```tsx
|
||||
// ❌ Bad, passing in the same value as the default value adds no value
|
||||
@@ -232,7 +235,7 @@ const Form = () => <EmailField value="username@email.com" />;
|
||||
|
||||
Try as much as possible to pass uninstanciated components as props, so chilren can decide on their own of what props they need to pass.
|
||||
|
||||
The most common example for that is icon components :
|
||||
The most common example for that is icon components:
|
||||
|
||||
```tsx
|
||||
const SomeParentComponent = () => <MyComponent Icon={MyIcon} />;
|
||||
@@ -261,13 +264,13 @@ Prop drilling, in the React context, refers to the practice of passing state var
|
||||
|
||||
3. **Reduced Component Reusability**: A component receiving numerous props solely for the purpose of passing them down becomes less general-purpose and harder to reuse in different contexts.
|
||||
|
||||
If you feel that you are using excessive prop drilling, see [state management best practices](/contributor/frontend/advanced/best-practices#state-management)
|
||||
If you feel that you are using excessive prop drilling, see [state management best practices](/contributor/frontend/advanced/best-practices#state-management).
|
||||
|
||||
## Imports
|
||||
|
||||
When importing, opt for the designated aliases rather than specifying complete or relative paths.
|
||||
|
||||
THE ALIASES
|
||||
**THE ALIASES**
|
||||
|
||||
```js
|
||||
{
|
||||
@@ -279,7 +282,7 @@ THE ALIASES
|
||||
}
|
||||
```
|
||||
|
||||
USAGE
|
||||
**USAGE**
|
||||
```tsx
|
||||
// ❌ Bad, specifies the entire relative path
|
||||
import {
|
||||
|
||||
@@ -1,11 +1,10 @@
|
||||
---
|
||||
title: Hotkeys
|
||||
sidebar_position: 11
|
||||
sidebar_custom_props:
|
||||
icon: TbKeyboard
|
||||
---
|
||||
|
||||
# Hotkeys
|
||||
|
||||
You can intercept any hotkey combination and execute a custom action.
|
||||
|
||||
We added a thin wrapper on top of [react-hotkeys-hook](https://react-hotkeys-hook.vercel.app/docs/intro) to make it more performant and to avoid unnecessary re-renders.
|
||||
|
||||
@@ -1,14 +1,13 @@
|
||||
---
|
||||
title: Style Guide
|
||||
sidebar_position: 4
|
||||
sidebar_custom_props:
|
||||
icon: TbPencil
|
||||
---
|
||||
|
||||
# Style guide
|
||||
|
||||
We define here the rules to follow when writing code.
|
||||
|
||||
Our goal is to have a consistent codebase, easy to read and easy to maintain.
|
||||
Our goal is to have a consistent codebase, which is easy to read and easy to maintain.
|
||||
|
||||
For this we prefer to tend towards being a bit more verbose than being too concise.
|
||||
|
||||
@@ -22,7 +21,7 @@ There are a lot of rules that are not defined here, but that are automatically c
|
||||
|
||||
Always use TSX functional components.
|
||||
|
||||
Do not use default import with const, because it's harder to read and harder to import with code completion.
|
||||
Do not use default `import` with `const`, because it's harder to read and harder to import with code completion.
|
||||
|
||||
```tsx
|
||||
// ❌ Bad, harder to read, harder to import with code completion
|
||||
@@ -135,9 +134,9 @@ onClick?.();
|
||||
|
||||
## TypeScript
|
||||
|
||||
### Use type instead of Interface
|
||||
### Use `type` instead of `Interface`
|
||||
|
||||
We decided to always use type instead of interface, because they almost always overlap, and type is more flexible.
|
||||
We decided to always use `type` instead of `interface`, because they almost always overlap, and `type` is more flexible.
|
||||
|
||||
```tsx
|
||||
// ❌ Bad
|
||||
@@ -155,7 +154,7 @@ type MyType = {
|
||||
|
||||
[String literals](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) are the go-to way to handle enum-like values in TypeScript. They are easier to extend with Pick and Omit, and offer a better developer experience, especially with code completion.
|
||||
|
||||
You can see why TypeScript recommend avoiding enums here : https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#enums
|
||||
You can see why TypeScript recommend avoiding enums [here](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#enums).
|
||||
|
||||
```tsx
|
||||
// ❌ Bad, utilizes an enum
|
||||
@@ -179,7 +178,7 @@ We recommend using enums that are generated by GraphQL codegen.
|
||||
|
||||
We also recommend using an enum when using an internal lib, so the internal lib doesn't have to expose a string literal type that is not related to the internal API.
|
||||
|
||||
Example :
|
||||
Example:
|
||||
|
||||
```TSX
|
||||
const {
|
||||
|
||||
@@ -57,28 +57,6 @@ A context is a way to pass data through the component tree without having to pas
|
||||
|
||||
See [React Context](https://react.dev/reference/react#context-hooks) for more details
|
||||
|
||||
### States
|
||||
|
||||
Contains the state management logic. We use [RecoilJS](https://recoiljs.org) for this.
|
||||
|
||||
- Selectors
|
||||
|
||||
See [RecoilJS Selectors](https://recoiljs.org/docs/basic-tutorial/selectors) for more details.
|
||||
|
||||
- Recoil Scope Contexts
|
||||
|
||||
More details will be added soon.
|
||||
|
||||
We still use React's built-in state management for state that is only used within a component.
|
||||
|
||||
### Hooks
|
||||
|
||||
See [Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks) for more details.
|
||||
|
||||
### Utils
|
||||
|
||||
Should only contain reusable pure functions. Otherwise, create custom hooks in the `hooks` folder.
|
||||
|
||||
### GraphQL
|
||||
|
||||
Includes fragments, queries, and mutations.
|
||||
@@ -87,17 +65,36 @@ See [GraphQL](https://graphql.org/learn/) for more details.
|
||||
|
||||
- Fragments
|
||||
|
||||
A fragment is a reusable piece of a query, which can be used in multiple places. By using fragments, it is easier to avoid duplicating code.
|
||||
A fragment is a reusable piece of a query, which can be used in multiple places. By using fragments, it is easier to avoid duplicating code.
|
||||
|
||||
See [GraphQL Fragments](https://graphql.org/learn/queries/#fragments) for more details.
|
||||
See [GraphQL Fragments](https://graphql.org/learn/queries/#fragments) for more details.
|
||||
|
||||
- Queries
|
||||
|
||||
See [GraphQL Queries](https://graphql.org/learn/queries/) for more details.
|
||||
See [GraphQL Queries](https://graphql.org/learn/queries/) for more details.
|
||||
|
||||
- Mutations
|
||||
|
||||
See [GraphQL Mutations](https://graphql.org/learn/queries/#mutations) for more details.
|
||||
See [GraphQL Mutations](https://graphql.org/learn/queries/#mutations) for more details.
|
||||
|
||||
### Hooks
|
||||
|
||||
See [Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks) for more details.
|
||||
|
||||
### States
|
||||
|
||||
Contains the state management logic. We use [RecoilJS](https://recoiljs.org) for this.
|
||||
|
||||
- Selectors: See [RecoilJS Selectors](https://recoiljs.org/docs/basic-tutorial/selectors) for more details.
|
||||
|
||||
- Recoil Scope Contexts: More details will be added soon.
|
||||
|
||||
We still use React's built-in state management for state that is only used within a component.
|
||||
|
||||
### Utils
|
||||
|
||||
Should only contain reusable pure functions. Otherwise, create custom hooks in the `hooks` folder.
|
||||
|
||||
|
||||
## UI
|
||||
|
||||
|
||||
@@ -1,11 +1,10 @@
|
||||
---
|
||||
title: Overview
|
||||
sidebar_position: 0
|
||||
sidebar_custom_props:
|
||||
icon: TbEyeglass
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
## Tech Stack
|
||||
|
||||
We took care of having a clean and simple stack, with minimal boilerplate code.
|
||||
|
||||
@@ -1,11 +1,10 @@
|
||||
---
|
||||
title: Work with Figma
|
||||
sidebar_position: 2
|
||||
sidebar_custom_props:
|
||||
icon: TbBrandFigma
|
||||
---
|
||||
|
||||
# Work with figma
|
||||
|
||||
Figma is a collaborative interface design tool that aids in bridging the communication barrier between designers and developers.
|
||||
In this guide, we'll go over how to collaborate with Twenty’s Figma.
|
||||
|
||||
@@ -30,7 +29,7 @@ With read-only access, you can't edit the design but you can access all features
|
||||
|
||||
### Use the Dev mode
|
||||
|
||||
Figma's Dev Mode enhances developers' productivity by providing easy design navigation, effective asset management, efficient communication tools, toolbox integrations, quick code snippets, and key layer information, bridging the gap between design and development. learn more at https://www.figma.com/dev-mode/
|
||||
Figma's Dev Mode enhances developers' productivity by providing easy design navigation, effective asset management, efficient communication tools, toolbox integrations, quick code snippets, and key layer information, bridging the gap between design and development. Learn more at https://www.figma.com/dev-mode/
|
||||
|
||||
Switch to the "Developer" mode in the right part of the toolbar to see design specs, copy CSS, and access assets.
|
||||
|
||||
@@ -41,7 +40,7 @@ Click on any element on the canvas and press the “Play” button at the top ri
|
||||
1. **Understanding transitions and animations:** In the Prototype mode, any transitions or animations added by a designer between screens or UI elements can be viewed, providing clear visual instructions to developers on the intended behavior and style.
|
||||
2. **Implementation Clarification:** A prototype can also be used to reduce ambiguities. Developers can interact with it to gain a better understanding of the functionality or appearance of particular elements.
|
||||
|
||||
For more comprehensive details and guidance on learning the Figma platform, you can visit the official Figma Documentation: https://help.figma.com/hc/en-us
|
||||
For more comprehensive details and guidance on learning the Figma platform, you can visit the official [Figma Documentation](https://help.figma.com/hc/en-us)
|
||||
|
||||
### Measure distances
|
||||
|
||||
|
||||
@@ -8,5 +8,4 @@ sidebar_custom_props:
|
||||
---
|
||||
|
||||
Welcome to the Frontend Development section of the documentation.
|
||||
Here you will find information about the frontend development process, the tools we use, and the best practices we follow.
|
||||
|
||||
Here you will find information about the frontend development process, the tools we use, and the best practices we follow.
|
||||
Reference in New Issue
Block a user