AGENTS.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Overview
6 
7This is the AFFiNE iOS application built with Capacitor, React, and TypeScript. It's a hybrid mobile app that wraps a React web application in a native iOS shell.
8 
9## Development Commands
10 
11### Build and Development
12 
13- `yarn dev` - Start development server with live reload
14- `yarn build` - Build the web application
15- `yarn sync` - Sync web assets with Capacitor iOS project
16- `yarn sync:dev` - Sync with development server (CAP_SERVER_URL=http://localhost:8080)
17- `yarn xcode` - Open Xcode project
18- `yarn codegen` - Generate GraphQL and Rust bindings
19- `xcodebuild -workspace App.xcworkspace -scheme App -destination 'platform=iOS Simulator,name=iPhone 15' build | xcbeautify` - Build iOS project with xcbeautify
20 
21### iOS Build Process
22 
231. `BUILD_TYPE=canary PUBLIC_PATH="/" yarn affine @affine/ios build` - Build web assets
242. `yarn affine @affine/ios cap sync` - Sync with iOS project
253. `yarn affine @affine/ios cap open ios` - Open in Xcode
26 
27### Live Reload Setup
28 
291. Run `yarn dev` and select `ios` for Distribution option
302. Run `yarn affine @affine/ios sync:dev`
313. Run `yarn affine @affine/ios cap open ios`
32 
33## Architecture
34 
35### Core Technologies
36 
37- **Capacitor 7.x** - Native iOS bridge
38- **React 19** - UI framework
39- **TypeScript** - Language
40- **Blocksuite** - Document editor
41- **DI Framework** - Dependency injection via `@toeverything/infra`
42 
43### Key Directories
44 
45- `src/` - React application source
46- `App/` - Native iOS Swift code
47- `dist/` - Built web assets
48- `capacitor-cordova-ios-plugins/` - Capacitor plugins
49 
50### Native Bridge Integration
51 
52The app exposes JavaScript APIs to native iOS code through `window` object:
53 
54- `getCurrentServerBaseUrl()` - Get current server URL
55- `getCurrentI18nLocale()` - Get current locale
56- `getAiButtonFeatureFlag()` - Check AI button feature flag
57- `getCurrentWorkspaceId()` - Get current workspace ID
58- `getCurrentDocId()` - Get current document ID
59- `getCurrentDocContentInMarkdown()` - Export current doc as markdown
60- `createNewDocByMarkdownInCurrentWorkspace()` - Import markdown as new doc
61 
62### Swift Code Style
63 
64Follow the guidelines in `AGENTS.md`:
65 
66- 2-space indentation
67- PascalCase for types, camelCase for properties/methods
68- Modern Swift features: `@Observable`, `async/await`, `actor`
69- Protocol-oriented design, dependency injection
70- Early returns, guard statements for optional unwrapping
71 
72### Build Configuration
73 
74- TypeScript config extends `../../../../tsconfig.web.json`
75- Webpack bundling via `@affine-tools/cli`
76- Capacitor config in `capacitor.config.ts`
77- GraphQL codegen via Apollo
78- Rust bindings generated via Uniffi
79 
80### Dependencies
81 
82- Workspace packages: `@affine/core`, `@affine/component`, `@affine/env`
83- Capacitor plugins: App, Browser, Haptics, Keyboard
84- React ecosystem: React Router, Next Themes
85- Storage: IDB, Yjs for collaborative editing
86 
87### Testing and Quality
88 
89- TypeScript strict mode enabled
90- ESLint/Prettier configuration from workspace root
91- No specific test commands in this package (tests likely in workspace root)
92 
93# Swift Code Style Guidelines
94 
95## Core Style
96 
97- **Indentation**: 2 spaces
98- **Braces**: Opening brace on same line
99- **Spacing**: Single space around operators and commas
100- **Naming**: PascalCase for types, camelCase for properties/methods
101 
102## File Organization
103 
104- Logical directory grouping
105- PascalCase files for types, `+` for extensions
106- Modular design with extensions
107 
108## Modern Swift Features
109 
110- **@Observable macro**: Replace `ObservableObject`/`@Published`
111- **Swift concurrency**: `async/await`, `Task`, `actor`, `@MainActor`
112- **Result builders**: Declarative APIs
113- **Property wrappers**: Use line breaks for long declarations
114- **Opaque types**: `some` for protocol returns
115 
116## Code Structure
117 
118- Early returns to reduce nesting
119- Guard statements for optional unwrapping
120- Single responsibility per type/extension
121- Value types over reference types
122 
123## Error Handling
124 
125- `Result` enum for typed errors
126- `throws`/`try` for propagation
127- Optional chaining with `guard let`/`if let`
128- Typed error definitions
129 
130## Architecture
131 
132- Avoid using protocol-oriented design unless necessary
133- Dependency injection over singletons
134- Composition over inheritance
135- Factory/Repository patterns
136 
137## Debug Assertions
138 
139- Use `assert()` for development-time invariant checking
140- Use `assertionFailure()` for unreachable code paths
141- Assertions removed in release builds for performance
142- Precondition checking with `precondition()` for fatal errors
143 
144## Memory Management
145 
146- `weak` references for cycles
147- `unowned` when guaranteed non-nil
148- Capture lists in closures
149- `deinit` for cleanup
150