move repository instructions to agents.md
This commit is contained in:
Samuel Newman
@@ -0,0 +1,588 @@
|
||||
# AGENTS.md – Bluesky Social App Development Guide
|
||||
|
||||
This document provides guidance for working effectively in the Bluesky Social app codebase.
|
||||
|
||||
## Project Overview
|
||||
|
||||
Bluesky Social is a cross-platform social media application built with React Native and Expo. It runs on iOS, Android, and Web, connecting to the AT Protocol (atproto) decentralized social network.
|
||||
|
||||
**Tech Stack:**
|
||||
|
||||
- React 19.2
|
||||
- React Native 0.86 with Expo 57
|
||||
- TypeScript 7
|
||||
- React Navigation 7 for routing
|
||||
- TanStack Query (React Query) for data fetching
|
||||
- Lingui 5 for internationalization
|
||||
- Custom design system called ALF (Application Layout Framework)
|
||||
|
||||
Prefer using the latest features available for each of these libraries (exact versions are found in `package.json`). For example, prefer `@lingui/react/macro` over `@lingui/react`. Suggest refactoring legacy or deprecated uses.
|
||||
|
||||
## Essential Commands
|
||||
|
||||
```bash
|
||||
# Development
|
||||
pnpm start # Start Expo dev server
|
||||
pnpm web # Start web version
|
||||
pnpm android # Run on Android
|
||||
pnpm ios # Run on iOS
|
||||
|
||||
# Testing & Quality
|
||||
# IMPORTANT: Always use these pnpm scripts, never call the underlying tools directly
|
||||
pnpm test # Run Jest tests
|
||||
pnpm lint # Run Oxlint
|
||||
pnpm typecheck # Run TypeScript type checking
|
||||
pnpm prettier # Run Prettier for code formatting
|
||||
|
||||
# Internationalization
|
||||
# DO NOT run these commands - extraction and compilation are handled by CI
|
||||
pnpm intl:extract # Extract translation strings (nightly CI job)
|
||||
pnpm intl:compile # Compile translations for runtime (nightly CI job)
|
||||
|
||||
# Build
|
||||
pnpm build-web # Build web version
|
||||
pnpm prebuild # Generate native projects
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── alf/ # Design system (ALF) - themes, atoms, tokens
|
||||
├── components/ # Shared UI components (Button, Dialog, Menu, etc.)
|
||||
├── screens/ # Full-page screen components (newer pattern)
|
||||
├── features/ # Macro-features that bridge components/screens
|
||||
├── view/
|
||||
│ ├── screens/ # Full-page screens (legacy location)
|
||||
│ ├── com/ # Reusable view components
|
||||
│ └── shell/ # App shell (navigation bars, tabs)
|
||||
├── state/
|
||||
│ ├── queries/ # TanStack Query hooks
|
||||
│ ├── preferences/ # User preferences (React Context)
|
||||
│ ├── session/ # Authentication state
|
||||
│ └── persisted/ # Persistent storage layer
|
||||
├── lib/ # Utilities, constants, helpers
|
||||
├── locale/ # i18n configuration and language files
|
||||
└── Navigation.tsx # Main navigation configuration
|
||||
```
|
||||
|
||||
### Project Structure in Depth
|
||||
|
||||
When building new things, follow these guidelines for where to put code.
|
||||
|
||||
#### Components vs Screens vs Features
|
||||
|
||||
**Components** are reusable UI elements that are not full screens. Should be
|
||||
platform-agnostic when possible. Examples: Button, Dialog, Menu, TextField. Put
|
||||
these in `/components` if they are shared across screens.
|
||||
|
||||
**Screens** are full-page components that represent a route in the app. They
|
||||
often contain multiple components and handle layout for a page. New screens
|
||||
should go in `/screens` (not `/view/screens`) to encourage better organization
|
||||
and separation from legacy code.
|
||||
|
||||
For complex screens that have specific components or data needs that _are not
|
||||
shared by other screens_, we encourage subdirectories within `/screens/<name>`
|
||||
e.g. `/screens/ProfileScreen/ProfileScreen.tsx` and
|
||||
`/screens/ProfileScreen/components/`.
|
||||
|
||||
**Features** are higher-level modules that may include context, data fetching,
|
||||
components, and utilities related to a specific feature e.g.
|
||||
`/features/liveNow`. They don't neatly fit into components or screens and often
|
||||
span multiple screens. This is an optional pattern for organizing complex
|
||||
features.
|
||||
|
||||
#### Legacy Directories
|
||||
|
||||
For the most part, avoid writing new files into the `/view` directory and
|
||||
subdirectories. This is the older pattern for organizing screens and components,
|
||||
and it has become a bit disorganized over time. New development should go into
|
||||
`/screens`, `/components`, and `/features`.
|
||||
|
||||
#### State
|
||||
|
||||
The `/state` directory is where we've historically put all our data fetching and
|
||||
state management logic. This is perfectly fine, but for new features, consider
|
||||
organizing state logic closer to the components that use it, either within a
|
||||
feature directory or co-located with a screen. The key is to keep related code
|
||||
together and avoid having "god files" with too much unrelated logic.
|
||||
|
||||
#### Lib
|
||||
|
||||
The `/lib` directory is for utilities and helpers that don't fit into other
|
||||
categories. This can include things like API clients, formatting functions,
|
||||
constants, and other shared logic.
|
||||
|
||||
#### Top Level Directories
|
||||
|
||||
Avoid writing new top-level subdirectories within `/src`. We've done this for a
|
||||
few things in the past that, but we have stronger patterns now. Examples:
|
||||
`/logger` should probably have been written into `/lib`. And `ageAssurance` is
|
||||
better classified within `/features`. We will probably migrate these things
|
||||
eventually.
|
||||
|
||||
### File and Directory Naming Conventions
|
||||
|
||||
Typically JS style for variables, functions, etc. We use ProudCamelCase for
|
||||
components, and camelCase directories and files.
|
||||
|
||||
For "macro" cases in `/features`, `/screens`, or `/components`, co-locate related
|
||||
code in a directory with an `index.tsx` main component plus sibling
|
||||
components/hooks/utils (e.g. `screens/ProfileScreen/index.tsx` +
|
||||
`screens/ProfileScreen/components/`). Keep related code together so it lives where
|
||||
someone would look for it. Don't overdo it: a component that fits in one file
|
||||
should just be `Component.tsx`, not `Component/index.tsx`.
|
||||
|
||||
Platform-specific files are covered under "Platform-Specific Code" below.
|
||||
|
||||
### Comments
|
||||
|
||||
Comment code when necessary to explain the “why” behind something; avoid
|
||||
comments that simply describe the code. Avoid Unicode characters in comments,
|
||||
e.g., use `-` not `—`.
|
||||
|
||||
Always use docblock (`/** */`) syntax for comments that document a type, type
|
||||
member, method, function, or variable. These are the comments a reader expects
|
||||
to find attached to a named declaration, and the docblock form makes that intent
|
||||
clear and surfaces nicely in editor tooltips.
|
||||
|
||||
```tsx
|
||||
type DateFieldProps = {
|
||||
/**
|
||||
* An empty string renders the placeholder and opens the picker at today (or
|
||||
* maximumDate, if earlier).
|
||||
*/
|
||||
value: string | Date
|
||||
}
|
||||
|
||||
/**
|
||||
* Date-only input. Accepts a string in the format YYYY-MM-DD, or a Date object.
|
||||
*/
|
||||
export function DateField() {}
|
||||
```
|
||||
|
||||
More generally, any multiline comment should use the `/* */` block syntax rather
|
||||
than stacked `//` lines. Reserve `//` for short, single-line comments.
|
||||
|
||||
```tsx
|
||||
/*
|
||||
* The picker requires a valid date, so when value is empty we fall back to
|
||||
* maximumDate (if set) or today.
|
||||
*/
|
||||
const fallbackDate = maximumDate ? toSimpleDateString(maximumDate) : today
|
||||
```
|
||||
|
||||
### Documentation and Tests Within Features
|
||||
|
||||
For larger features or components, co-locate documentation and tests with the
|
||||
code. A `README.md` in the directory (the `/Component/index.tsx` pattern lends
|
||||
itself well to this) can document the whole feature, and feature-specific tests
|
||||
belong alongside it as `Component.test.tsx` or in a `__tests__/` subdirectory.
|
||||
Both are optional.
|
||||
|
||||
## Styling System (ALF)
|
||||
|
||||
ALF is the custom design system. Tailwind-inspired naming with underscores
|
||||
instead of hyphens. Static atoms (`atoms as a`) are theme-independent; theme
|
||||
atoms/palette come from `useTheme()` (`t.atoms.bg`, `t.palette.primary_500`).
|
||||
Style props take an array of atoms + theme atoms + raw styles.
|
||||
|
||||
Order atoms by: flexbox (`a.flex_row`), spacing (`a.px_md`), text (`a.font_bold`),
|
||||
themes (`t.atoms.text`), then raw styles (`{backgroundColor: t.palette.primary_500}`).
|
||||
|
||||
```tsx
|
||||
import {atoms as a, useTheme} from '#/alf'
|
||||
|
||||
const t = useTheme()
|
||||
<View style={[a.flex_row, a.gap_md, a.p_lg, t.atoms.bg]} />
|
||||
```
|
||||
|
||||
### Key Concepts
|
||||
|
||||
Static atoms live in `a.*` (e.g. `a.flex_row`, `a.p_md`, `a.rounded_md`,
|
||||
`a.text_lg`). Theme atoms/palette come from `useTheme()` (`t.atoms.bg`,
|
||||
`t.atoms.text`, `t.atoms.border_contrast_low`, `t.palette.primary_500`).
|
||||
|
||||
**Platform utilities** (`import {web, native, ios, android, platform} from '#/alf'`)
|
||||
return conditional styles inline in a style array: `web({cursor: 'pointer'})`,
|
||||
`native({paddingBottom: 20})`, `platform({ios: {...}, android: {...}, web: {...}})`.
|
||||
|
||||
**Breakpoints:** `const {gtPhone, gtMobile, gtTablet} = useBreakpoints()` from `#/alf`.
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
- Spacing: `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl` (t-shirt sizes)
|
||||
- Text: `text_xs`, `text_sm`, `text_md`, `text_lg`, `text_xl`
|
||||
- Gaps/Padding: `gap_sm`, `p_md`, `px_lg`, `py_xl`
|
||||
- Flex: `flex_row`, `flex_1`, `align_center`, `justify_between`
|
||||
- Borders: `border`, `border_t`, `rounded_md`, `rounded_full`
|
||||
|
||||
## Component Patterns
|
||||
|
||||
- Prefer fragment shorthand over `Fragment` unless a `key` is needed.
|
||||
- Prefer functions over arrow functions for component declarations.
|
||||
- Prefer prop destructuring via parameters over a const within the component.
|
||||
- Prefer inline types over `Props` types or interfaces.
|
||||
- Set reasonable defaults for optional props.
|
||||
- Prefer the implicit global `React` for types over `type` imports.
|
||||
|
||||
```tsx
|
||||
import {Fragment} from 'react'
|
||||
import {View} from 'react-native'
|
||||
import {Trans} from '@lingui/react/macro'
|
||||
|
||||
import {Text} from '#/components/Typography'
|
||||
|
||||
function MyComponent({
|
||||
items = [],
|
||||
children,
|
||||
}: {
|
||||
items?: string[]
|
||||
children: React.ReactNode
|
||||
}) {
|
||||
return (
|
||||
<>
|
||||
<View>
|
||||
<Text>
|
||||
<Trans>Example</Trans>
|
||||
</Text>
|
||||
</View>
|
||||
<View>
|
||||
{items.map((item, index) => (
|
||||
<Fragment key={item}>
|
||||
<Text>{index}</Text>
|
||||
<Text>{item}</Text>
|
||||
</Fragment>
|
||||
))}
|
||||
{children}
|
||||
</View>
|
||||
</>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Dialog Component
|
||||
|
||||
Lives in `#/components/Dialog`. Bottom sheet on native, modal on web. Manage
|
||||
state with `useDialogControl()`. `Dialog.Handle` renders native-only, `Dialog.Close`
|
||||
web-only. CRITICAL: run any post-close action inside the `control.close(() => ...)`
|
||||
callback (see Footguns). Compound-component usage; canonical example in any dialog
|
||||
under `#/components`.
|
||||
|
||||
### Menu Component
|
||||
|
||||
Lives in `#/components/Menu`. Dropdown on web, bottom sheet dialog on native.
|
||||
`Menu.Divider` is web-only, `Menu.ContainerItem` native-only. Compound API
|
||||
(`Menu.Root` / `Menu.Trigger` / `Menu.Outer` / `Menu.Group` / `Menu.Item`); grep
|
||||
existing usages across the app for a canonical example.
|
||||
|
||||
### Button Component
|
||||
|
||||
`import {Button, ButtonText, ButtonIcon} from '#/components/Button'`. Props:
|
||||
|
||||
- `color`: `'primary'` | `'secondary'` | `'negative'` | `'primary_subtle'` | `'negative_subtle'` | `'secondary_inverted'`
|
||||
- `size`: `'tiny'` | `'small'` | `'large'`
|
||||
- `shape`: `'default'` (pill) | `'round'` | `'square'` | `'rectangular'`
|
||||
- `variant`: `'solid'` | `'outline'` | `'ghost'` (deprecated, prefer `color`)
|
||||
|
||||
### TextField
|
||||
|
||||
Compound component at `#/components/forms/TextField` (`TextField.LabelText`,
|
||||
`TextField.Root`, `TextField.Icon`, `TextField.Input`). Prefer `defaultValue` over
|
||||
`value` (see Footguns).
|
||||
|
||||
### Typography
|
||||
|
||||
`import {Text, H1, H2, P} from '#/components/Typography'`. The `Text` default style
|
||||
is `[a.text_sm, a.leading_snug, t.atoms.text]`. Pass the `emoji` prop to any `Text`
|
||||
that may contain emoji - user-generated text (display names etc.) almost always
|
||||
does, so only omit it for static, emoji-free strings: `<Text emoji>Hello!</Text>`.
|
||||
|
||||
## Internationalization (i18n)
|
||||
|
||||
All user-facing strings must be wrapped for translation using Lingui. Include `comment` and/or `context` props when necessary to avoid ambiguity, e.g., “Post” as a noun vs a verb.
|
||||
|
||||
Prefer using `t` via `import {useLingui} '@lingui/react/macro'` vs `_` via `import {useLingui} from '@lingui/react'`. Alias `t` to `l` to avoid collisions with `const t = useTheme()`. Refactor existing uses of ``_(msg`foo`)`` to use `` l`foo` ``.
|
||||
|
||||
Prefer Unicode punctuation over keyboard punctuation, e.g., `“quote”` over `"quote"`. Prefer en dashes preceded by a non-breaking space over em dashes, e.g., `one – two` over `one—two`.
|
||||
|
||||
```tsx
|
||||
import {plural} from '@lingui/core/macro'
|
||||
import {Trans, useLingui} from '@lingui/react/macro'
|
||||
|
||||
function MyComponent() {
|
||||
const {t: l} = useLingui()
|
||||
|
||||
// Simple strings - use the l macro
|
||||
const title = l`Settings`
|
||||
const errorMessage = l({
|
||||
message: 'Something went wrong',
|
||||
comment: 'Generic error message for unknown/unhandled errors.',
|
||||
context: 'Toast',
|
||||
})
|
||||
|
||||
// Strings with variables
|
||||
const greeting = l`Hello, ${name}!`
|
||||
|
||||
// Pluralization
|
||||
const countLabel = plural(count, {
|
||||
one: '# item',
|
||||
other: '# items',
|
||||
})
|
||||
|
||||
// JSX content - use Trans component
|
||||
return (
|
||||
<Text>
|
||||
<Trans>
|
||||
Welcome to <Text style={a.font_bold}>Bluesky</Text>, {name}!
|
||||
</Trans>
|
||||
</Text>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Prefer `i18n.date` for date and time formatting. This ensures formatting is re-applied when the language changes at runtime. Refactor existing uses of `Intl.DateTimeFormat` to use `i18n.date`.
|
||||
|
||||
```tsx
|
||||
import {useLingui} from '@lingui/react/macro'
|
||||
|
||||
function MyComponent() {
|
||||
const {i18n} = useLingui()
|
||||
|
||||
const createdAt = new Date()
|
||||
|
||||
return i18n.date(createdAt, {
|
||||
dateStyle: 'medium',
|
||||
timeStyle: 'medium',
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
**Commands:**
|
||||
|
||||
```bash
|
||||
# DO NOT run these commands - extraction and compilation are handled by a nightly CI job
|
||||
pnpm intl:extract # Extract new strings to locale files
|
||||
pnpm intl:compile # Compile translations for runtime
|
||||
```
|
||||
|
||||
## State Management
|
||||
|
||||
### TanStack Query (Data Fetching)
|
||||
|
||||
Follow the established pattern in `src/state/queries/`; `src/state/queries/feed.ts`
|
||||
is a good canonical reference (it uses `createQueryKey`, matching key roots,
|
||||
`useInfiniteQuery`, and `persistedVersion`).
|
||||
|
||||
- Build query keys with `createQueryKey(root, args)` (from `#/state/queries/util`)
|
||||
using an object for `args`. The key root variable should match the hook name.
|
||||
- Naming conventions: `use[Name]Query` for queries, `use[Name]Mutation` for
|
||||
mutations, `use[Name]CacheMutation` for helpers that mutate cached data directly.
|
||||
- Stale times come from `STALE` in `src/state/queries/index.ts`: `STALE.SECONDS.FIFTEEN`,
|
||||
`STALE.MINUTES.ONE`, `STALE.MINUTES.FIVE`, `STALE.HOURS.ONE`, `STALE.INFINITY`.
|
||||
- Paginated atproto APIs (those returning a `cursor`) use `useInfiniteQuery` with
|
||||
`getNextPageParam: page => page.cursor`; flatten results with
|
||||
`data?.pages.flatMap(page => page.items) ?? []`.
|
||||
- Persist a query across restarts by passing options:
|
||||
`createQueryKey(root, args, {persistedVersion: n})`. Bumping `n` clears the old
|
||||
persisted data and refetches - do this whenever the data shape changes.
|
||||
- Error handling in mutations: don't log network errors (just inform the user),
|
||||
handle typed XRPC errors specifically (e.g. `err instanceof SomeNsid.SomeError`),
|
||||
and send unexpected errors to `logger.error('...', {safeMessage: error})`.
|
||||
|
||||
### Preferences (React Context)
|
||||
|
||||
Boolean/simple UI preferences are exposed as paired hooks from `#/state/preferences`,
|
||||
e.g. `useAutoplayDisabled()` / `useSetAutoplayDisabled()`.
|
||||
|
||||
### Session State
|
||||
|
||||
`import {useSession, useAgent} from '#/state/session'`. `useSession()` gives
|
||||
`hasSession` and `currentAccount`; `useAgent()` gives the atproto agent for API calls.
|
||||
|
||||
## Navigation
|
||||
|
||||
React Navigation with type-safe route params. Type a screen with
|
||||
`NativeStackScreenProps<CommonNavigatorParams, 'X'>` (`route`/`navigation` come
|
||||
from props; params via `route.params`). Navigate programmatically with
|
||||
`useNavigation()`, or the `navigate` helper from `#/Navigation`. Config lives in
|
||||
`src/Navigation.tsx`, routes in `src/routes.ts`, types in `src/lib/routes/types.ts`.
|
||||
|
||||
## Platform-Specific Code
|
||||
|
||||
Use file extensions for platform-specific implementations. The bundler resolves
|
||||
them automatically - just import the base path normally, never a conditional
|
||||
`require()`.
|
||||
|
||||
```
|
||||
Component.tsx # Shared/default
|
||||
Component.web.tsx # Web-only
|
||||
Component.native.tsx # iOS + Android
|
||||
Component.ios.tsx # iOS-only
|
||||
Component.android.tsx # Android-only
|
||||
```
|
||||
|
||||
Prefer grouping variants into a `Component/` directory (`index.tsx`,
|
||||
`index.web.tsx`, `index.native.tsx`) rather than sibling `Component.web.tsx` files,
|
||||
so the shared surface reads as one "macro" module (e.g. `src/components/Dialog/index.tsx`
|
||||
native vs `index.web.tsx` web). The app has both patterns; the directory form is
|
||||
preferred for new code.
|
||||
|
||||
```tsx
|
||||
// CORRECT - bundler picks storage.ts or storage.web.ts automatically
|
||||
import * as storage from '#/state/drafts/storage'
|
||||
|
||||
// WRONG - don't use require() or conditional imports for platform files
|
||||
const storage = IS_NATIVE
|
||||
? require('#/state/drafts/storage')
|
||||
: require('#/state/drafts/storage.web')
|
||||
```
|
||||
|
||||
Runtime platform detection (not for imports): `import {IS_WEB, IS_NATIVE, IS_IOS, IS_ANDROID} from '#/env'`.
|
||||
|
||||
## Import Aliases
|
||||
|
||||
Always use the `#/` alias for absolute imports:
|
||||
|
||||
```tsx
|
||||
// Good
|
||||
import {useSession} from '#/state/session'
|
||||
import {atoms as a, useTheme} from '#/alf'
|
||||
import {Button} from '#/components/Button'
|
||||
|
||||
// Avoid
|
||||
import {useSession} from '../../../state/session'
|
||||
```
|
||||
|
||||
## Footguns
|
||||
|
||||
Common pitfalls to avoid in this codebase:
|
||||
|
||||
### Dialog Close Callback (Critical)
|
||||
|
||||
**Always use `control.close(() => ...)` when performing actions after closing a dialog.** The callback ensures the action runs after the dialog's close animation completes. Failing to do this causes race conditions with React state updates.
|
||||
|
||||
```tsx
|
||||
// WRONG - causes bugs with state updates, navigation, opening other dialogs
|
||||
const onConfirm = () => {
|
||||
control.close()
|
||||
navigation.navigate('Home') // May race with dialog animation
|
||||
}
|
||||
|
||||
// WRONG - same problem
|
||||
const onConfirm = () => {
|
||||
control.close()
|
||||
otherDialogControl.open() // Will likely fail or cause visual glitches
|
||||
}
|
||||
|
||||
// CORRECT - action runs after dialog fully closes
|
||||
const onConfirm = () => {
|
||||
control.close(() => {
|
||||
navigation.navigate('Home')
|
||||
})
|
||||
}
|
||||
|
||||
// CORRECT - opening another dialog after close
|
||||
const onConfirm = () => {
|
||||
control.close(() => {
|
||||
otherDialogControl.open()
|
||||
})
|
||||
}
|
||||
|
||||
// CORRECT - state updates after close
|
||||
const onConfirm = () => {
|
||||
control.close(() => {
|
||||
setSomeState(newValue)
|
||||
onCallback?.()
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
This applies to:
|
||||
|
||||
- Navigation (`navigation.navigate()`, `navigation.push()`)
|
||||
- Opening other dialogs or menus
|
||||
- State updates that affect UI (`setState`, `queryClient.invalidateQueries`)
|
||||
- Callbacks passed from parent components
|
||||
|
||||
The Menu component on iOS specifically uses this pattern – see `src/components/Menu/index.tsx:151`.
|
||||
|
||||
### Controlled vs Uncontrolled Inputs
|
||||
|
||||
Prefer `defaultValue` over `value` for TextInput on the old architecture:
|
||||
|
||||
```tsx
|
||||
// Preferred - uncontrolled
|
||||
<TextField.Input
|
||||
defaultValue={initialEmail}
|
||||
onChangeText={setEmail}
|
||||
/>
|
||||
|
||||
// Avoid when possible - controlled (can cause performance issues)
|
||||
<TextField.Input
|
||||
value={email}
|
||||
onChangeText={setEmail}
|
||||
/>
|
||||
```
|
||||
|
||||
### Platform-Specific Behavior
|
||||
|
||||
Some components behave differently across platforms:
|
||||
|
||||
- `Dialog.Handle` – Only renders on native (drag handle for bottom sheet)
|
||||
- `Dialog.Close` – Only renders on web (X button)
|
||||
- `Menu.Divider` – Only renders on web
|
||||
- `Menu.ContainerItem` – Only works on native
|
||||
|
||||
Always test on multiple platforms when using these components.
|
||||
|
||||
### React Compiler is Enabled
|
||||
|
||||
This codebase uses React Compiler, so **don't proactively add `useMemo` or `useCallback`**. The compiler handles memoization automatically.
|
||||
|
||||
```tsx
|
||||
// UNNECESSARY - React Compiler handles this
|
||||
const handlePress = useCallback(() => {
|
||||
doSomething()
|
||||
}, [doSomething])
|
||||
|
||||
// JUST WRITE THIS
|
||||
const handlePress = () => {
|
||||
doSomething()
|
||||
}
|
||||
```
|
||||
|
||||
Only use `useMemo`/`useCallback` when you have a specific reason, such as:
|
||||
|
||||
- The value is immediately used in an effect's dependency array
|
||||
- You're passing a callback to a non-React library that needs referential stability
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Accessibility**: Always provide `label` prop for interactive elements, use `accessibilityHint` where helpful
|
||||
|
||||
2. **Translations**: Wrap ALL user-facing strings with the `` l`…` `` macro or the `<Trans>` component
|
||||
|
||||
3. **Styling**: Combine static atoms with theme atoms, use platform utilities for platform-specific styles
|
||||
|
||||
4. **State**: Use TanStack Query for server state, React Context for UI preferences
|
||||
|
||||
5. **Components**: Check if a component exists in `#/components/` before creating new ones
|
||||
|
||||
6. **Types**: Define explicit types for props, use `NativeStackScreenProps` for screens
|
||||
|
||||
7. **Testing**: Components should have `testID` props for E2E testing
|
||||
|
||||
## Key Files Reference
|
||||
|
||||
| Purpose | Location |
|
||||
| ----------------- | -------------------------------------------- |
|
||||
| Theme definitions | `src/alf/themes.ts` |
|
||||
| Design tokens | `src/alf/tokens.ts` |
|
||||
| Static atoms | `src/alf/atoms.ts` (extends `@bsky.app/alf`) |
|
||||
| Navigation config | `src/Navigation.tsx` |
|
||||
| Route definitions | `src/routes.ts` |
|
||||
| Route types | `src/lib/routes/types.ts` |
|
||||
| Query hooks | `src/state/queries/*.ts` |
|
||||
| Session state | `src/state/session/index.tsx` |
|
||||
| i18n setup | `src/locale/i18n.ts` |
|
||||
@@ -1,588 +1 @@
|
||||
# CLAUDE.md – Bluesky Social App Development Guide
|
||||
|
||||
This document provides guidance for working effectively in the Bluesky Social app codebase.
|
||||
|
||||
## Project Overview
|
||||
|
||||
Bluesky Social is a cross-platform social media application built with React Native and Expo. It runs on iOS, Android, and Web, connecting to the AT Protocol (atproto) decentralized social network.
|
||||
|
||||
**Tech Stack:**
|
||||
|
||||
- React 19.2
|
||||
- React Native 0.86 with Expo 57
|
||||
- TypeScript 7
|
||||
- React Navigation 7 for routing
|
||||
- TanStack Query (React Query) for data fetching
|
||||
- Lingui 5 for internationalization
|
||||
- Custom design system called ALF (Application Layout Framework)
|
||||
|
||||
Prefer using the latest features available for each of these libraries (exact versions are found in `package.json`). For example, prefer `@lingui/react/macro` over `@lingui/react`. Suggest refactoring legacy or deprecated uses.
|
||||
|
||||
## Essential Commands
|
||||
|
||||
```bash
|
||||
# Development
|
||||
pnpm start # Start Expo dev server
|
||||
pnpm web # Start web version
|
||||
pnpm android # Run on Android
|
||||
pnpm ios # Run on iOS
|
||||
|
||||
# Testing & Quality
|
||||
# IMPORTANT: Always use these pnpm scripts, never call the underlying tools directly
|
||||
pnpm test # Run Jest tests
|
||||
pnpm lint # Run Oxlint
|
||||
pnpm typecheck # Run TypeScript type checking
|
||||
pnpm prettier # Run Prettier for code formatting
|
||||
|
||||
# Internationalization
|
||||
# DO NOT run these commands - extraction and compilation are handled by CI
|
||||
pnpm intl:extract # Extract translation strings (nightly CI job)
|
||||
pnpm intl:compile # Compile translations for runtime (nightly CI job)
|
||||
|
||||
# Build
|
||||
pnpm build-web # Build web version
|
||||
pnpm prebuild # Generate native projects
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── alf/ # Design system (ALF) - themes, atoms, tokens
|
||||
├── components/ # Shared UI components (Button, Dialog, Menu, etc.)
|
||||
├── screens/ # Full-page screen components (newer pattern)
|
||||
├── features/ # Macro-features that bridge components/screens
|
||||
├── view/
|
||||
│ ├── screens/ # Full-page screens (legacy location)
|
||||
│ ├── com/ # Reusable view components
|
||||
│ └── shell/ # App shell (navigation bars, tabs)
|
||||
├── state/
|
||||
│ ├── queries/ # TanStack Query hooks
|
||||
│ ├── preferences/ # User preferences (React Context)
|
||||
│ ├── session/ # Authentication state
|
||||
│ └── persisted/ # Persistent storage layer
|
||||
├── lib/ # Utilities, constants, helpers
|
||||
├── locale/ # i18n configuration and language files
|
||||
└── Navigation.tsx # Main navigation configuration
|
||||
```
|
||||
|
||||
### Project Structure in Depth
|
||||
|
||||
When building new things, follow these guidelines for where to put code.
|
||||
|
||||
#### Components vs Screens vs Features
|
||||
|
||||
**Components** are reusable UI elements that are not full screens. Should be
|
||||
platform-agnostic when possible. Examples: Button, Dialog, Menu, TextField. Put
|
||||
these in `/components` if they are shared across screens.
|
||||
|
||||
**Screens** are full-page components that represent a route in the app. They
|
||||
often contain multiple components and handle layout for a page. New screens
|
||||
should go in `/screens` (not `/view/screens`) to encourage better organization
|
||||
and separation from legacy code.
|
||||
|
||||
For complex screens that have specific components or data needs that _are not
|
||||
shared by other screens_, we encourage subdirectories within `/screens/<name>`
|
||||
e.g. `/screens/ProfileScreen/ProfileScreen.tsx` and
|
||||
`/screens/ProfileScreen/components/`.
|
||||
|
||||
**Features** are higher-level modules that may include context, data fetching,
|
||||
components, and utilities related to a specific feature e.g.
|
||||
`/features/liveNow`. They don't neatly fit into components or screens and often
|
||||
span multiple screens. This is an optional pattern for organizing complex
|
||||
features.
|
||||
|
||||
#### Legacy Directories
|
||||
|
||||
For the most part, avoid writing new files into the `/view` directory and
|
||||
subdirectories. This is the older pattern for organizing screens and components,
|
||||
and it has become a bit disorganized over time. New development should go into
|
||||
`/screens`, `/components`, and `/features`.
|
||||
|
||||
#### State
|
||||
|
||||
The `/state` directory is where we've historically put all our data fetching and
|
||||
state management logic. This is perfectly fine, but for new features, consider
|
||||
organizing state logic closer to the components that use it, either within a
|
||||
feature directory or co-located with a screen. The key is to keep related code
|
||||
together and avoid having "god files" with too much unrelated logic.
|
||||
|
||||
#### Lib
|
||||
|
||||
The `/lib` directory is for utilities and helpers that don't fit into other
|
||||
categories. This can include things like API clients, formatting functions,
|
||||
constants, and other shared logic.
|
||||
|
||||
#### Top Level Directories
|
||||
|
||||
Avoid writing new top-level subdirectories within `/src`. We've done this for a
|
||||
few things in the past that, but we have stronger patterns now. Examples:
|
||||
`/logger` should probably have been written into `/lib`. And `ageAssurance` is
|
||||
better classified within `/features`. We will probably migrate these things
|
||||
eventually.
|
||||
|
||||
### File and Directory Naming Conventions
|
||||
|
||||
Typically JS style for variables, functions, etc. We use ProudCamelCase for
|
||||
components, and camelCase directories and files.
|
||||
|
||||
For "macro" cases in `/features`, `/screens`, or `/components`, co-locate related
|
||||
code in a directory with an `index.tsx` main component plus sibling
|
||||
components/hooks/utils (e.g. `screens/ProfileScreen/index.tsx` +
|
||||
`screens/ProfileScreen/components/`). Keep related code together so it lives where
|
||||
someone would look for it. Don't overdo it: a component that fits in one file
|
||||
should just be `Component.tsx`, not `Component/index.tsx`.
|
||||
|
||||
Platform-specific files are covered under "Platform-Specific Code" below.
|
||||
|
||||
### Comments
|
||||
|
||||
Comment code when necessary to explain the “why” behind something; avoid
|
||||
comments that simply describe the code. Avoid Unicode characters in comments,
|
||||
e.g., use `-` not `—`.
|
||||
|
||||
Always use docblock (`/** */`) syntax for comments that document a type, type
|
||||
member, method, function, or variable. These are the comments a reader expects
|
||||
to find attached to a named declaration, and the docblock form makes that intent
|
||||
clear and surfaces nicely in editor tooltips.
|
||||
|
||||
```tsx
|
||||
type DateFieldProps = {
|
||||
/**
|
||||
* An empty string renders the placeholder and opens the picker at today (or
|
||||
* maximumDate, if earlier).
|
||||
*/
|
||||
value: string | Date
|
||||
}
|
||||
|
||||
/**
|
||||
* Date-only input. Accepts a string in the format YYYY-MM-DD, or a Date object.
|
||||
*/
|
||||
export function DateField() {}
|
||||
```
|
||||
|
||||
More generally, any multiline comment should use the `/* */` block syntax rather
|
||||
than stacked `//` lines. Reserve `//` for short, single-line comments.
|
||||
|
||||
```tsx
|
||||
/*
|
||||
* The picker requires a valid date, so when value is empty we fall back to
|
||||
* maximumDate (if set) or today.
|
||||
*/
|
||||
const fallbackDate = maximumDate ? toSimpleDateString(maximumDate) : today
|
||||
```
|
||||
|
||||
### Documentation and Tests Within Features
|
||||
|
||||
For larger features or components, co-locate documentation and tests with the
|
||||
code. A `README.md` in the directory (the `/Component/index.tsx` pattern lends
|
||||
itself well to this) can document the whole feature, and feature-specific tests
|
||||
belong alongside it as `Component.test.tsx` or in a `__tests__/` subdirectory.
|
||||
Both are optional.
|
||||
|
||||
## Styling System (ALF)
|
||||
|
||||
ALF is the custom design system. Tailwind-inspired naming with underscores
|
||||
instead of hyphens. Static atoms (`atoms as a`) are theme-independent; theme
|
||||
atoms/palette come from `useTheme()` (`t.atoms.bg`, `t.palette.primary_500`).
|
||||
Style props take an array of atoms + theme atoms + raw styles.
|
||||
|
||||
Order atoms by: flexbox (`a.flex_row`), spacing (`a.px_md`), text (`a.font_bold`),
|
||||
themes (`t.atoms.text`), then raw styles (`{backgroundColor: t.palette.primary_500}`).
|
||||
|
||||
```tsx
|
||||
import {atoms as a, useTheme} from '#/alf'
|
||||
|
||||
const t = useTheme()
|
||||
<View style={[a.flex_row, a.gap_md, a.p_lg, t.atoms.bg]} />
|
||||
```
|
||||
|
||||
### Key Concepts
|
||||
|
||||
Static atoms live in `a.*` (e.g. `a.flex_row`, `a.p_md`, `a.rounded_md`,
|
||||
`a.text_lg`). Theme atoms/palette come from `useTheme()` (`t.atoms.bg`,
|
||||
`t.atoms.text`, `t.atoms.border_contrast_low`, `t.palette.primary_500`).
|
||||
|
||||
**Platform utilities** (`import {web, native, ios, android, platform} from '#/alf'`)
|
||||
return conditional styles inline in a style array: `web({cursor: 'pointer'})`,
|
||||
`native({paddingBottom: 20})`, `platform({ios: {...}, android: {...}, web: {...}})`.
|
||||
|
||||
**Breakpoints:** `const {gtPhone, gtMobile, gtTablet} = useBreakpoints()` from `#/alf`.
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
- Spacing: `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl` (t-shirt sizes)
|
||||
- Text: `text_xs`, `text_sm`, `text_md`, `text_lg`, `text_xl`
|
||||
- Gaps/Padding: `gap_sm`, `p_md`, `px_lg`, `py_xl`
|
||||
- Flex: `flex_row`, `flex_1`, `align_center`, `justify_between`
|
||||
- Borders: `border`, `border_t`, `rounded_md`, `rounded_full`
|
||||
|
||||
## Component Patterns
|
||||
|
||||
- Prefer fragment shorthand over `Fragment` unless a `key` is needed.
|
||||
- Prefer functions over arrow functions for component declarations.
|
||||
- Prefer prop destructuring via parameters over a const within the component.
|
||||
- Prefer inline types over `Props` types or interfaces.
|
||||
- Set reasonable defaults for optional props.
|
||||
- Prefer the implicit global `React` for types over `type` imports.
|
||||
|
||||
```tsx
|
||||
import {Fragment} from 'react'
|
||||
import {View} from 'react-native'
|
||||
import {Trans} from '@lingui/react/macro'
|
||||
|
||||
import {Text} from '#/components/Typography'
|
||||
|
||||
function MyComponent({
|
||||
items = [],
|
||||
children,
|
||||
}: {
|
||||
items?: string[]
|
||||
children: React.ReactNode
|
||||
}) {
|
||||
return (
|
||||
<>
|
||||
<View>
|
||||
<Text>
|
||||
<Trans>Example</Trans>
|
||||
</Text>
|
||||
</View>
|
||||
<View>
|
||||
{items.map((item, index) => (
|
||||
<Fragment key={item}>
|
||||
<Text>{index}</Text>
|
||||
<Text>{item}</Text>
|
||||
</Fragment>
|
||||
))}
|
||||
{children}
|
||||
</View>
|
||||
</>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Dialog Component
|
||||
|
||||
Lives in `#/components/Dialog`. Bottom sheet on native, modal on web. Manage
|
||||
state with `useDialogControl()`. `Dialog.Handle` renders native-only, `Dialog.Close`
|
||||
web-only. CRITICAL: run any post-close action inside the `control.close(() => ...)`
|
||||
callback (see Footguns). Compound-component usage; canonical example in any dialog
|
||||
under `#/components`.
|
||||
|
||||
### Menu Component
|
||||
|
||||
Lives in `#/components/Menu`. Dropdown on web, bottom sheet dialog on native.
|
||||
`Menu.Divider` is web-only, `Menu.ContainerItem` native-only. Compound API
|
||||
(`Menu.Root` / `Menu.Trigger` / `Menu.Outer` / `Menu.Group` / `Menu.Item`); grep
|
||||
existing usages across the app for a canonical example.
|
||||
|
||||
### Button Component
|
||||
|
||||
`import {Button, ButtonText, ButtonIcon} from '#/components/Button'`. Props:
|
||||
|
||||
- `color`: `'primary'` | `'secondary'` | `'negative'` | `'primary_subtle'` | `'negative_subtle'` | `'secondary_inverted'`
|
||||
- `size`: `'tiny'` | `'small'` | `'large'`
|
||||
- `shape`: `'default'` (pill) | `'round'` | `'square'` | `'rectangular'`
|
||||
- `variant`: `'solid'` | `'outline'` | `'ghost'` (deprecated, prefer `color`)
|
||||
|
||||
### TextField
|
||||
|
||||
Compound component at `#/components/forms/TextField` (`TextField.LabelText`,
|
||||
`TextField.Root`, `TextField.Icon`, `TextField.Input`). Prefer `defaultValue` over
|
||||
`value` (see Footguns).
|
||||
|
||||
### Typography
|
||||
|
||||
`import {Text, H1, H2, P} from '#/components/Typography'`. The `Text` default style
|
||||
is `[a.text_sm, a.leading_snug, t.atoms.text]`. Pass the `emoji` prop to any `Text`
|
||||
that may contain emoji - user-generated text (display names etc.) almost always
|
||||
does, so only omit it for static, emoji-free strings: `<Text emoji>Hello!</Text>`.
|
||||
|
||||
## Internationalization (i18n)
|
||||
|
||||
All user-facing strings must be wrapped for translation using Lingui. Include `comment` and/or `context` props when necessary to avoid ambiguity, e.g., “Post” as a noun vs a verb.
|
||||
|
||||
Prefer using `t` via `import {useLingui} '@lingui/react/macro'` vs `_` via `import {useLingui} from '@lingui/react'`. Alias `t` to `l` to avoid collisions with `const t = useTheme()`. Refactor existing uses of ``_(msg`foo`)`` to use `` l`foo` ``.
|
||||
|
||||
Prefer Unicode punctuation over keyboard punctuation, e.g., `“quote”` over `"quote"`. Prefer en dashes preceded by a non-breaking space over em dashes, e.g., `one – two` over `one—two`.
|
||||
|
||||
```tsx
|
||||
import {plural} from '@lingui/core/macro'
|
||||
import {Trans, useLingui} from '@lingui/react/macro'
|
||||
|
||||
function MyComponent() {
|
||||
const {t: l} = useLingui()
|
||||
|
||||
// Simple strings - use the l macro
|
||||
const title = l`Settings`
|
||||
const errorMessage = l({
|
||||
message: 'Something went wrong',
|
||||
comment: 'Generic error message for unknown/unhandled errors.',
|
||||
context: 'Toast',
|
||||
})
|
||||
|
||||
// Strings with variables
|
||||
const greeting = l`Hello, ${name}!`
|
||||
|
||||
// Pluralization
|
||||
const countLabel = plural(count, {
|
||||
one: '# item',
|
||||
other: '# items',
|
||||
})
|
||||
|
||||
// JSX content - use Trans component
|
||||
return (
|
||||
<Text>
|
||||
<Trans>
|
||||
Welcome to <Text style={a.font_bold}>Bluesky</Text>, {name}!
|
||||
</Trans>
|
||||
</Text>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Prefer `i18n.date` for date and time formatting. This ensures formatting is re-applied when the language changes at runtime. Refactor existing uses of `Intl.DateTimeFormat` to use `i18n.date`.
|
||||
|
||||
```tsx
|
||||
import {useLingui} from '@lingui/react/macro'
|
||||
|
||||
function MyComponent() {
|
||||
const {i18n} = useLingui()
|
||||
|
||||
const createdAt = new Date()
|
||||
|
||||
return i18n.date(createdAt, {
|
||||
dateStyle: 'medium',
|
||||
timeStyle: 'medium',
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
**Commands:**
|
||||
|
||||
```bash
|
||||
# DO NOT run these commands - extraction and compilation are handled by a nightly CI job
|
||||
pnpm intl:extract # Extract new strings to locale files
|
||||
pnpm intl:compile # Compile translations for runtime
|
||||
```
|
||||
|
||||
## State Management
|
||||
|
||||
### TanStack Query (Data Fetching)
|
||||
|
||||
Follow the established pattern in `src/state/queries/`; `src/state/queries/feed.ts`
|
||||
is a good canonical reference (it uses `createQueryKey`, matching key roots,
|
||||
`useInfiniteQuery`, and `persistedVersion`).
|
||||
|
||||
- Build query keys with `createQueryKey(root, args)` (from `#/state/queries/util`)
|
||||
using an object for `args`. The key root variable should match the hook name.
|
||||
- Naming conventions: `use[Name]Query` for queries, `use[Name]Mutation` for
|
||||
mutations, `use[Name]CacheMutation` for helpers that mutate cached data directly.
|
||||
- Stale times come from `STALE` in `src/state/queries/index.ts`: `STALE.SECONDS.FIFTEEN`,
|
||||
`STALE.MINUTES.ONE`, `STALE.MINUTES.FIVE`, `STALE.HOURS.ONE`, `STALE.INFINITY`.
|
||||
- Paginated atproto APIs (those returning a `cursor`) use `useInfiniteQuery` with
|
||||
`getNextPageParam: page => page.cursor`; flatten results with
|
||||
`data?.pages.flatMap(page => page.items) ?? []`.
|
||||
- Persist a query across restarts by passing options:
|
||||
`createQueryKey(root, args, {persistedVersion: n})`. Bumping `n` clears the old
|
||||
persisted data and refetches - do this whenever the data shape changes.
|
||||
- Error handling in mutations: don't log network errors (just inform the user),
|
||||
handle typed XRPC errors specifically (e.g. `err instanceof SomeNsid.SomeError`),
|
||||
and send unexpected errors to `logger.error('...', {safeMessage: error})`.
|
||||
|
||||
### Preferences (React Context)
|
||||
|
||||
Boolean/simple UI preferences are exposed as paired hooks from `#/state/preferences`,
|
||||
e.g. `useAutoplayDisabled()` / `useSetAutoplayDisabled()`.
|
||||
|
||||
### Session State
|
||||
|
||||
`import {useSession, useAgent} from '#/state/session'`. `useSession()` gives
|
||||
`hasSession` and `currentAccount`; `useAgent()` gives the atproto agent for API calls.
|
||||
|
||||
## Navigation
|
||||
|
||||
React Navigation with type-safe route params. Type a screen with
|
||||
`NativeStackScreenProps<CommonNavigatorParams, 'X'>` (`route`/`navigation` come
|
||||
from props; params via `route.params`). Navigate programmatically with
|
||||
`useNavigation()`, or the `navigate` helper from `#/Navigation`. Config lives in
|
||||
`src/Navigation.tsx`, routes in `src/routes.ts`, types in `src/lib/routes/types.ts`.
|
||||
|
||||
## Platform-Specific Code
|
||||
|
||||
Use file extensions for platform-specific implementations. The bundler resolves
|
||||
them automatically - just import the base path normally, never a conditional
|
||||
`require()`.
|
||||
|
||||
```
|
||||
Component.tsx # Shared/default
|
||||
Component.web.tsx # Web-only
|
||||
Component.native.tsx # iOS + Android
|
||||
Component.ios.tsx # iOS-only
|
||||
Component.android.tsx # Android-only
|
||||
```
|
||||
|
||||
Prefer grouping variants into a `Component/` directory (`index.tsx`,
|
||||
`index.web.tsx`, `index.native.tsx`) rather than sibling `Component.web.tsx` files,
|
||||
so the shared surface reads as one "macro" module (e.g. `src/components/Dialog/index.tsx`
|
||||
native vs `index.web.tsx` web). The app has both patterns; the directory form is
|
||||
preferred for new code.
|
||||
|
||||
```tsx
|
||||
// CORRECT - bundler picks storage.ts or storage.web.ts automatically
|
||||
import * as storage from '#/state/drafts/storage'
|
||||
|
||||
// WRONG - don't use require() or conditional imports for platform files
|
||||
const storage = IS_NATIVE
|
||||
? require('#/state/drafts/storage')
|
||||
: require('#/state/drafts/storage.web')
|
||||
```
|
||||
|
||||
Runtime platform detection (not for imports): `import {IS_WEB, IS_NATIVE, IS_IOS, IS_ANDROID} from '#/env'`.
|
||||
|
||||
## Import Aliases
|
||||
|
||||
Always use the `#/` alias for absolute imports:
|
||||
|
||||
```tsx
|
||||
// Good
|
||||
import {useSession} from '#/state/session'
|
||||
import {atoms as a, useTheme} from '#/alf'
|
||||
import {Button} from '#/components/Button'
|
||||
|
||||
// Avoid
|
||||
import {useSession} from '../../../state/session'
|
||||
```
|
||||
|
||||
## Footguns
|
||||
|
||||
Common pitfalls to avoid in this codebase:
|
||||
|
||||
### Dialog Close Callback (Critical)
|
||||
|
||||
**Always use `control.close(() => ...)` when performing actions after closing a dialog.** The callback ensures the action runs after the dialog's close animation completes. Failing to do this causes race conditions with React state updates.
|
||||
|
||||
```tsx
|
||||
// WRONG - causes bugs with state updates, navigation, opening other dialogs
|
||||
const onConfirm = () => {
|
||||
control.close()
|
||||
navigation.navigate('Home') // May race with dialog animation
|
||||
}
|
||||
|
||||
// WRONG - same problem
|
||||
const onConfirm = () => {
|
||||
control.close()
|
||||
otherDialogControl.open() // Will likely fail or cause visual glitches
|
||||
}
|
||||
|
||||
// CORRECT - action runs after dialog fully closes
|
||||
const onConfirm = () => {
|
||||
control.close(() => {
|
||||
navigation.navigate('Home')
|
||||
})
|
||||
}
|
||||
|
||||
// CORRECT - opening another dialog after close
|
||||
const onConfirm = () => {
|
||||
control.close(() => {
|
||||
otherDialogControl.open()
|
||||
})
|
||||
}
|
||||
|
||||
// CORRECT - state updates after close
|
||||
const onConfirm = () => {
|
||||
control.close(() => {
|
||||
setSomeState(newValue)
|
||||
onCallback?.()
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
This applies to:
|
||||
|
||||
- Navigation (`navigation.navigate()`, `navigation.push()`)
|
||||
- Opening other dialogs or menus
|
||||
- State updates that affect UI (`setState`, `queryClient.invalidateQueries`)
|
||||
- Callbacks passed from parent components
|
||||
|
||||
The Menu component on iOS specifically uses this pattern – see `src/components/Menu/index.tsx:151`.
|
||||
|
||||
### Controlled vs Uncontrolled Inputs
|
||||
|
||||
Prefer `defaultValue` over `value` for TextInput on the old architecture:
|
||||
|
||||
```tsx
|
||||
// Preferred - uncontrolled
|
||||
<TextField.Input
|
||||
defaultValue={initialEmail}
|
||||
onChangeText={setEmail}
|
||||
/>
|
||||
|
||||
// Avoid when possible - controlled (can cause performance issues)
|
||||
<TextField.Input
|
||||
value={email}
|
||||
onChangeText={setEmail}
|
||||
/>
|
||||
```
|
||||
|
||||
### Platform-Specific Behavior
|
||||
|
||||
Some components behave differently across platforms:
|
||||
|
||||
- `Dialog.Handle` – Only renders on native (drag handle for bottom sheet)
|
||||
- `Dialog.Close` – Only renders on web (X button)
|
||||
- `Menu.Divider` – Only renders on web
|
||||
- `Menu.ContainerItem` – Only works on native
|
||||
|
||||
Always test on multiple platforms when using these components.
|
||||
|
||||
### React Compiler is Enabled
|
||||
|
||||
This codebase uses React Compiler, so **don't proactively add `useMemo` or `useCallback`**. The compiler handles memoization automatically.
|
||||
|
||||
```tsx
|
||||
// UNNECESSARY - React Compiler handles this
|
||||
const handlePress = useCallback(() => {
|
||||
doSomething()
|
||||
}, [doSomething])
|
||||
|
||||
// JUST WRITE THIS
|
||||
const handlePress = () => {
|
||||
doSomething()
|
||||
}
|
||||
```
|
||||
|
||||
Only use `useMemo`/`useCallback` when you have a specific reason, such as:
|
||||
|
||||
- The value is immediately used in an effect's dependency array
|
||||
- You're passing a callback to a non-React library that needs referential stability
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Accessibility**: Always provide `label` prop for interactive elements, use `accessibilityHint` where helpful
|
||||
|
||||
2. **Translations**: Wrap ALL user-facing strings with the `` l`…` `` macro or the `<Trans>` component
|
||||
|
||||
3. **Styling**: Combine static atoms with theme atoms, use platform utilities for platform-specific styles
|
||||
|
||||
4. **State**: Use TanStack Query for server state, React Context for UI preferences
|
||||
|
||||
5. **Components**: Check if a component exists in `#/components/` before creating new ones
|
||||
|
||||
6. **Types**: Define explicit types for props, use `NativeStackScreenProps` for screens
|
||||
|
||||
7. **Testing**: Components should have `testID` props for E2E testing
|
||||
|
||||
## Key Files Reference
|
||||
|
||||
| Purpose | Location |
|
||||
| ----------------- | -------------------------------------------- |
|
||||
| Theme definitions | `src/alf/themes.ts` |
|
||||
| Design tokens | `src/alf/tokens.ts` |
|
||||
| Static atoms | `src/alf/atoms.ts` (extends `@bsky.app/alf`) |
|
||||
| Navigation config | `src/Navigation.tsx` |
|
||||
| Route definitions | `src/routes.ts` |
|
||||
| Route types | `src/lib/routes/types.ts` |
|
||||
| Query hooks | `src/state/queries/*.ts` |
|
||||
| Session state | `src/state/session/index.tsx` |
|
||||
| i18n setup | `src/locale/i18n.ts` |
|
||||
@AGENTS.md
|
||||
|
||||
Reference in New Issue
Block a user