Codebase Best Practices
Styling a component
We recommend styling components using our design style guide.
The colors are defined in variable.css
, and the fonts are in fonts.css
.
We are strongly opinionated about adding new variables/tokens to the colors. After careful research, the colors have been chosen to respect the freeCodeCamp brand identity, developer experience, and accessibility.
The !important
keyword may be used to override values in some cases (e.g. accessibility concerns). You should add a comment describing the issue, so it doesnβt get removed in future refactoring.
RTL support
We are striving to support right-to-left (RTL) layout in the codebase for languages that are read in this direction. For this, you need to be mindful of how to style components. Here are some quick rules of thumb to follow:
- Donβt use
float
properties- Use Flexbox and Grid layouts instead, as they have RTL support already built-in, and those will be easier to maintain and review.
- Donβt define the direction while using
margin
andpadding
: it may seem harmless to usepadding-right
andmargin-left
, but these directions arenβt mirrored when the layout changes to RTL, and adding counter values for them in the RTL file makes maintaining the codebase harder.- Use logical properties for them: You can add the same spacing by using
padding-inline-end
andmargin-inline-start
, and you wonβt need to worry about RTL layout, as they follow where the line starts and ends, and you wonβt need to add any extra values in the RTL files, so people wonβt need to remember to change the same values in two files.
- Use logical properties for them: You can add the same spacing by using
- Donβt use
!important
infont-family
: RTL layout uses different fonts compared to the LTR layout, when you add!important
in thefont-family
property it affects the RTL layout too.
General JavaScript
In most cases, our linter will warn of any formatting which goes against this codebaseβs preferred practice.
It is encouraged to use functional components over class-based components.
Specific TypeScript
Migrating a JavaScript File to TypeScript
Retaining Git File History
Sometimes changing the file from <filename>.js
to <filename>.ts
(or .tsx
) causes the original file to be deleted, and a new one created, and other times the filename just changes - in terms of Git. Ideally, we want the file history to be preserved.
The best bet at achieving this is to:
- Rename the file
- Commit with the flag
--no-verify
to prevent Husky from complaining about the lint errors - Refactor to TypeScript for migration, in a separate commit
:::note Editors like VSCode are still likely to show you the file has been deleted
and a new one created. If you use the CLI to git add .
, then VSCode will show the
file as renamed in stage :::
Naming Conventions
Interfaces and Types
For the most part, it is encouraged to use interface declarations over type declarations.
React Component Props - suffix with Props
React Stateful Components - suffix with State
Default - object name in PascalCase
//β #### Redux Actions β>
//β TODO: Once refactored to TS, showcase naming convention for Reducers/Actions and how to type dispatch funcs β>
Redux
Action Definitions
How to Reduce
How to Dispatch
Within a component, import the actions and selectors needed.
//β ### Redux Types File β>
//β The types associated with the Redux store state are located in client/src/redux/types.ts
β¦ β>
API
Testing
The api/
tests are split into two parts:
- Unit tests
- Integration tests
Unit Tests
Unit tests isolate a single function or component. The tests do not need mocking, but will require fixtures.
The unit tests are located in a new file adjacent to the file exporting that is being tested:
Integration Tests
Integration tests test the API as a whole. The tests will require mocking and should not require fixtures beyond the database seeding data and a method for authentication.
Typically, each integration test file will be directly related to a route. The integration tests are located in the api/tests/
directory: