jollywhoppers.com
Bluesky app fork with some witchin' additions 💫
witchsky.app
bluesky
fork
client
Add docs on directory structures and naming conventions (#10002)
authored by
Eric Bailey
and committed by
GitHub
8b8acb7b
1a487d09
+116
CLAUDE.md
+116
CLAUDE.md
···
46
46
├── alf/ # Design system (ALF) - themes, atoms, tokens
47
47
├── components/ # Shared UI components (Button, Dialog, Menu, etc.)
48
48
├── screens/ # Full-page screen components (newer pattern)
49
+
├── features/ # Macro-features that bridge components/screens
49
50
├── view/
50
51
│ ├── screens/ # Full-page screens (legacy location)
51
52
│ ├── com/ # Reusable view components
···
59
60
├── locale/ # i18n configuration and language files
60
61
└── Navigation.tsx # Main navigation configuration
61
62
```
63
+
64
+
### Project Structure in Depth
65
+
66
+
When building new things, follow these guidelines for where to put code.
67
+
68
+
#### Components vs Screens vs Features
69
+
70
+
**Components** are reusable UI elements that are not full screens. Should be
71
+
platform-agnostic when possible. Examples: Button, Dialog, Menu, TextField. Put
72
+
these in `/components` if they are shared across screens.
73
+
74
+
**Screens** are full-page components that represent a route in the app. They
75
+
often contain multiple components and handle layout for a page. New screens
76
+
should go in `/screens` (not `/view/screens`) to encourage better organization
77
+
and separation from legacy code.
78
+
79
+
For complex screens that have specific components or data needs that _are not
80
+
shared by other screens_, we encourage subdirectoreis within `/screens/<name>`
81
+
e.g. `/screens/ProfileScreen/ProfileScreen.tsx` and
82
+
`/screens/ProfileScreen/components/`.
83
+
84
+
**Features** are higher-level modules that may include context, data fetching,
85
+
components, and utilities related to a specific feature e.g.
86
+
`/features/liveNow`. They don't neatly fit into components or screens and often
87
+
span multiple screens. This is an optional pattern for organizing complex
88
+
features.
89
+
90
+
#### Legacy Directories
91
+
92
+
For the most part, avoid writing new files into the `/view` directory and
93
+
subdirectories. This is the older pattern for organizing screens and components,
94
+
and it has become a bit disorganized over time. New development should go into
95
+
`/screens`, `/components`, and `/features`.
96
+
97
+
#### State
98
+
99
+
The `/state` directory is where we've historically put all our data fetching and
100
+
state management logic. This is perfectly fine, but for new features, consider
101
+
organizing state logic closer to the components that use it, either within a
102
+
feature directory or co-located with a screen. The key is to keep related code
103
+
together and avoid having "god files" with too much unrelated logic.
104
+
105
+
#### Lib
106
+
107
+
The `/lib` directory is for utilities and helpers that don't fit into other
108
+
categories. This can include things like API clients, formatting functions,
109
+
constants, and other shared logic.
110
+
111
+
#### Top Level Directories
112
+
113
+
Avoid writing new top-level subdirectories within `/src`. We've done this for a
114
+
few things in the past that, but we have stronger patterns now. Examples:
115
+
`/logger` should probably have been written into `/lib`. And `ageAssurance` is
116
+
better classified within `/features`. We will probably migrate these things
117
+
eventually.
118
+
119
+
### File and Directory Naming Conventions
120
+
121
+
Typically JS style for variables, functions, etc. We use ProudCamelCase for
122
+
components, and camelCase directories and files.
123
+
124
+
When organizing new code, consider if it fits into a single file, or if it
125
+
should be broken down into multiple files. For "macro" component cases, or
126
+
things that live in `/features` or `/screens`, we often follow a pattern of
127
+
having an `index.tsx` for the main component, and then co-locating related
128
+
components, hooks, and utilities in the same directory. For example:
129
+
130
+
```
131
+
src
132
+
├── screens/
133
+
│ ├── ProfileScreen/
134
+
│ │ ├── index.tsx # Main screen component
135
+
│ │ ├── components/ # Sub-components used only by this screen
136
+
```
137
+
138
+
Similar patterns can be found in `/features` and `/components`. The idea here is
139
+
to keep related code together and make it easier to navigate.
140
+
141
+
You should ask yourself: if someone new was looking for the code related to this
142
+
feature or screen, where would they expect to find it? Organizing code in a way
143
+
that matches developer expectations can make the codebase much more
144
+
approachable. Being able to say "Live Now stuff lives in `/features/liveNow`" is
145
+
easier to understand than having it scattered across multiple directories.
146
+
147
+
No need to go overboard with this. If a component or feature fits into a single
148
+
file, there's no reason to have a `/Component/index.tsx` file when it could just
149
+
be `/Component.tsx`. Use your judgment based on the complexity and amount of
150
+
related code.
151
+
152
+
#### Platform Specific Files
153
+
154
+
We have conflicting patterns in the app for this. The preferred approach is to
155
+
group platform-specific files into a directory as much as possible. For example,
156
+
rather than having `Component.tsx`, `Component.web.tsx`, and
157
+
`Component.native.tsx` in the same directory, we prefer to have a `Component/`
158
+
directory with `index.tsx`, `index.web.tsx`, and `index.native.tsx`. This keeps
159
+
related code together and gives us a better visual cue that there are probably
160
+
other files contained within this "macro" feature, whereas `Component.tsx` on
161
+
its own looks more like a single component file.
162
+
163
+
### Documentation and Tests Within Features
164
+
165
+
For larger features or components, it's helpful to include a README.md file
166
+
within the directory that explains the purpose of the feature, how it works, and
167
+
any important implementation details. The `/Component/index.tsx` pattern lends
168
+
itself well to this, since the `index.tsx` can be the main component file, and
169
+
the `README.md` can provide documentation for the whole feature. This is
170
+
optional, but can be a nice way to keep documentation close to the code it
171
+
describes.
172
+
173
+
Similarly, if there are tests that are specific to a component or feature, it
174
+
can be helpful to include them in the same directory, either as
175
+
`Component.test.tsx` or in a `__tests__/` subdirectory. This keeps everything
176
+
related to the component or feature in one place and makes it easier to find and
177
+
maintain tests.
62
178
63
179
## Styling System (ALF)
64
180