Initial commit
This commit is contained in:
Igor Martyniuk
@@ -0,0 +1,249 @@
|
||||
# File & Folder Naming
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Naming Convention](#naming-convention)
|
||||
- [Folders](#folders)
|
||||
- [Component Files](#component-files)
|
||||
- [Hook Files](#hook-files)
|
||||
- [Utility & Helper Files](#utility--helper-files)
|
||||
- [Other TypeScript Files](#other-typescript-files)
|
||||
- [Examples by Layer](#examples-by-layer)
|
||||
- [Case-Only Rename Problem (macOS + Git)](#case-only-rename-problem-macos--git)
|
||||
- [Required: Correct Rename Procedure](#required-correct-rename-procedure)
|
||||
- [Making Git Case-Sensitive on macOS](#making-git-case-sensitive-on-macos)
|
||||
- [Important Reality Check](#important-reality-check)
|
||||
|
||||
## Naming Convention
|
||||
|
||||
We follow **standard React community naming conventions**:
|
||||
|
||||
These conventions apply to frontend apps and to module folders inside those apps. For example, `apps/admin/src/core/FileManager` may use PascalCase because it is a product module folder, while its layer folders such as `data`, `entities`, `providers`, `pages`, `view`, and `shared` stay lowercase.
|
||||
|
||||
| Type | Convention | Example |
|
||||
| ---------------------- | -------------------------------------------- | ------------------------------------- |
|
||||
| Folders | lowercase (PascalCase for component folders) | `user/`, `shared/`, `CreateUserForm/` |
|
||||
| React component files | PascalCase | `UserProfile.tsx`, `Button.tsx` |
|
||||
| Hook files | camelCase (`use` prefix) | `useDebounce.ts`, `useToggle.ts` |
|
||||
| Utility / helper files | camelCase | `formatDate.ts`, `generateId.ts` |
|
||||
| API / service files | camelCase (acronyms uppercase) | `userAPI.ts`, `productAPI.ts` |
|
||||
| DTO / mapper files | camelCase (acronyms uppercase) | `userDTO.ts`, `userMapper.ts` |
|
||||
| Type / interface files | camelCase | `types.ts`, `dto.ts`, `interfaces.ts` |
|
||||
| Constants files | camelCase | `constants.ts`, `formConstants.ts` |
|
||||
| Config / entry files | camelCase | `index.ts`, `queryClient.ts` |
|
||||
|
||||
### Folders
|
||||
|
||||
Layer and infrastructure folders use **lowercase**.
|
||||
Component, form, and widget folders use **PascalCase** — matching the component they contain.
|
||||
|
||||
```
|
||||
src/
|
||||
data/ # lowercase — layer folder
|
||||
user/ # lowercase — entity folder
|
||||
product/
|
||||
view/ # lowercase — layer folder
|
||||
components/
|
||||
forms/
|
||||
CreateUserForm/ # PascalCase — component folder
|
||||
widgets/
|
||||
UserProfileWidget/
|
||||
shared/
|
||||
ui/
|
||||
hooks/
|
||||
lib/
|
||||
```
|
||||
|
||||
### Component Files
|
||||
|
||||
React component files use **PascalCase** — matching the name of the exported component.
|
||||
|
||||
```
|
||||
UserProfile.tsx
|
||||
ProductCard.tsx
|
||||
LoginButton.tsx
|
||||
UserProfileWidget.tsx
|
||||
CreateProductForm.tsx
|
||||
```
|
||||
|
||||
### Hook Files
|
||||
|
||||
Hook files use **camelCase** and always start with `use`.
|
||||
|
||||
```
|
||||
useDebounce.ts
|
||||
useToggle.ts
|
||||
useLocalStorage.ts
|
||||
useUserQuery.ts
|
||||
useCreateProductMutation.ts
|
||||
```
|
||||
|
||||
### Utility & Helper Files
|
||||
|
||||
Utility and helper files use **camelCase**.
|
||||
|
||||
```
|
||||
formatDate.ts
|
||||
formatCurrency.ts
|
||||
generateId.ts
|
||||
sleep.ts
|
||||
```
|
||||
|
||||
### Other TypeScript Files
|
||||
|
||||
All other `.ts` files (APIs, DTOs, mappers, types, config) use **camelCase**, with acronyms kept uppercase.
|
||||
|
||||
```
|
||||
userAPI.ts
|
||||
userDTO.ts
|
||||
userMapper.ts
|
||||
types.ts
|
||||
constants.ts
|
||||
queryClient.ts
|
||||
axiosInstance.ts
|
||||
```
|
||||
|
||||
### Examples by Layer
|
||||
|
||||
#### `shared/`
|
||||
|
||||
```plaintext
|
||||
shared/
|
||||
├── ui/
|
||||
│ ├── Button.tsx
|
||||
│ ├── Modal.tsx
|
||||
│ └── Card.tsx
|
||||
│
|
||||
├── hooks/
|
||||
│ ├── useDebounce.ts
|
||||
│ ├── useToggle.ts
|
||||
│ └── useLocalStorage.ts
|
||||
│
|
||||
├── lib/
|
||||
│ ├── axios/
|
||||
│ │ └── axiosInstance.ts
|
||||
│ └── query/
|
||||
│ └── queryClient.ts
|
||||
│
|
||||
└── utils/
|
||||
├── formatDate.ts
|
||||
└── formatCurrency.ts
|
||||
```
|
||||
|
||||
#### `data/`
|
||||
|
||||
```plaintext
|
||||
data/
|
||||
├── user/
|
||||
│ ├── userAPI.ts
|
||||
│ ├── hooks.ts # or useUserQuery.ts, useCreateUserMutation.ts
|
||||
│ ├── userDTO.ts
|
||||
│ └── userMapper.ts
|
||||
│
|
||||
└── product/
|
||||
├── productAPI.ts
|
||||
├── hooks.ts
|
||||
├── productDTO.ts
|
||||
└── productMapper.ts
|
||||
```
|
||||
|
||||
#### `providers/`
|
||||
|
||||
```plaintext
|
||||
providers/
|
||||
├── AppProviders.tsx
|
||||
├── QueryProvider.tsx
|
||||
├── RouterProvider.tsx
|
||||
├── ThemeProvider.tsx
|
||||
├── AuthProvider.tsx
|
||||
├── I18nProvider.tsx
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
#### `view/`
|
||||
|
||||
```plaintext
|
||||
view/
|
||||
├── components/
|
||||
│ ├── UserAvatar.tsx
|
||||
│ └── ProductCard.tsx
|
||||
│
|
||||
├── widgets/
|
||||
│ └── UserProfileWidget/
|
||||
│ ├── index.ts
|
||||
│ └── UserProfileWidget.tsx
|
||||
│
|
||||
└── forms/
|
||||
└── CreateUserForm/
|
||||
├── form.ts
|
||||
├── Component.tsx
|
||||
├── submit.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
## Case-Only Rename Problem (macOS + Git)
|
||||
|
||||
macOS file systems are **case-insensitive by default**, while Git is **case-sensitive internally**.
|
||||
|
||||
Renaming a file like `api.ts` → `Api.ts` may:
|
||||
|
||||
- Not be detected by Git
|
||||
- Break CI (Linux environments are case-sensitive)
|
||||
- Cause inconsistent repository state
|
||||
|
||||
### REQUIRED: Correct Rename Procedure
|
||||
|
||||
If you **must rename a file or folder by case only**, you are required to perform a two-step rename.
|
||||
|
||||
#### Step 1 — Rename to Temporary Name
|
||||
|
||||
```bash
|
||||
git mv userApi.ts userApi-temp.ts
|
||||
git commit -m "chore: temporary rename userApi.ts to userApi-temp.ts"
|
||||
```
|
||||
|
||||
#### Step 2 — Rename to Final Name
|
||||
|
||||
```bash
|
||||
git mv userApi-temp.ts UserApi.ts
|
||||
git commit -m "chore: rename userApi-temp.ts to UserApi.ts (case change)"
|
||||
```
|
||||
|
||||
### Rules
|
||||
|
||||
- Never rename by case only in one step
|
||||
- Always use an intermediate name
|
||||
- Always commit both steps
|
||||
- Applies to files and folders
|
||||
- Do not rely only on IDE rename
|
||||
- Always verify with `git status`
|
||||
|
||||
### Making Git Case-Sensitive on macOS
|
||||
|
||||
By default, Git on macOS usually has:
|
||||
|
||||
`core.ignorecase=true`
|
||||
|
||||
This makes Git ignore case-only changes.
|
||||
|
||||
#### Set Case Sensitivity for This Repository
|
||||
|
||||
```bash
|
||||
git config core.ignorecase false
|
||||
```
|
||||
|
||||
#### Verify:
|
||||
|
||||
```bash
|
||||
git config core.ignorecase
|
||||
```
|
||||
|
||||
It should return: `false`
|
||||
|
||||
### Important Reality Check
|
||||
|
||||
Even if `core.ignorecase=false`:
|
||||
|
||||
- macOS file system is still case-insensitive
|
||||
- Case-only renames can still behave unexpectedly
|
||||
- The two-step rename process is still the safest approach
|
||||
Reference in New Issue
Block a user