admin/docs/apps-architecture/react-frontend/naming.md

File & Folder Naming

Table of Contents

• Naming Convention
  • Folders
  • Component Files
  • Hook Files
  • Utility & Helper Files
  • Other TypeScript Files
  • Examples by Layer
• Case-Only Rename Problem (macOS + Git)
  • Required: Correct Rename Procedure
  • Making Git Case-Sensitive on macOS
  • 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/

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/

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/

providers/
├── AppProviders.tsx
├── QueryProvider.tsx
├── RouterProvider.tsx
├── ThemeProvider.tsx
├── AuthProvider.tsx
├── I18nProvider.tsx
└── index.ts

view/

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

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

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

git config core.ignorecase false

Verify:

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