Full Source Access
Complete control over all components
Custom Layouts
Build entirely new user flows
Your Codebase
Maintain your own version and roadmap
Professional Workflow
Full development environment setup
Pick Fork & Extend only after validating that Dynamic UI and Component Styling cannot achieve your goals with acceptable complexity.
When to Choose Fork & Extend
Fork & Extend is ideal when you need: ✅ Complete customization freedom – Modify any rendering or data flow✅ Custom user flows – Create navigation patterns not exposed by standard pages
✅ Deep integration – Embed UIKit pieces inside a complex existing architecture
✅ Performance tuning – Rework virtualization, batching, caching layers
✅ Extensible domain logic – Inject proprietary moderation, ranking, analytics
✅ Long-term ownership – Maintain an internal roadmap independent of upstream release cadence ❌ Simple branding only – Use Dynamic UI (faster, zero maintenance)
❌ Just per-component styling – Use Component Styling (lower effort)
❌ Limited engineering capacity – Forks require continual rebasing
❌ Short-lived experiment – Prefer a lighter extension path first
If you expect to contribute improvements back later, maintain a light fork (few direct core edits) and use extension points / adapters where possible.
Repository Directory
| Platform | Repository | Language / Stack | Package / Tooling | Notes |
|---|---|---|---|---|
| iOS | https://github.com/AmityCo/ASC-UIKit-iOS-OpenSource | Swift | SwiftPM | SwiftUI wrappers & UIKit interop |
| Android | https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Android | Kotlin (Compose) | Gradle (KTS) | Jetpack Compose components |
| Web (React) | https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Web-OpenSource | TypeScript / React | pnpm / npm / Vite (variant) | Modular import points |
| React Native | https://github.com/AmityCo/Amity-Social-UIKit-React-Native-CLI-OpenSource | TypeScript / RN | Yarn / Metro | Native bridges in subpackages |
| Flutter | https://github.com/AmityCo/Amity-Social-UIKit-Flutter-Opensource | Dart / Flutter | pub | Composable widgets |
Forking Strategies
Light Fork (Recommended)
Light Fork (Recommended)
Keep upstream directory structure; override via extension hooks, subclassing, dependency injection. Avoid editing core logic; instead patch behavior through public APIs.
Selective Extraction
Selective Extraction
Copy only needed modules (e.g. feed + reactions) into your mono‑repo, leaving update path harder but reducing dependency surface.
Heavy Fork
Heavy Fork
Broad internal rewrites; highest divergence risk; only for teams prepared to maintain a private long‑term branch & merge engine changes manually.
Recommended Workflow
1
Fork Upstream
Create fork in your org; clone locally.
2
Add Upstream Remote
git remote add upstream <canonical-repo-url>3
Baseline Audit
Run tests, lint, build to ensure clean starting point.
4
Create Feature Branches
One logical customization per branch; keep diffs focused.
5
Abstraction First
Add interfaces / adapters before altering core flows.
6
Rebase Regularly
git fetch upstream && git rebase upstream/main (avoid giant merge commits).7
Tag Internal Releases
Semantic pre-release tags (e.g.
4.2.1-fork.3).Git Operations (Examples)
Extension Points & Patterns
| Pattern | Use Case | Example |
|---|---|---|
| Subclass / Inherit | Override rendering | Custom PostCell layout |
| Composition Wrapper | Inject analytics / guards | Wrap FeedList with tracking HOC / decorator |
| Dependency Injection | Swap services (auth, storage) | Provide custom AuthProvider |
| Behavior Strategy Object | Change navigation / flows | Custom CommentTrayBehavior |
| Theming Adapter | Align design tokens | Map internal design system → UIKit tokens |
Prefer adding a new extension seam over editing multiple call sites—easier to rebase.
Upgrade Strategy
Track Upstream Tags
Track Upstream Tags
Changelog Diffing
Changelog Diffing
Automate
git diff upstream/vX.Y.Z..upstream/vX.Y.(Z+1) to surface structural changes.Contract Tests
Contract Tests
Write smoke tests for critical flows (auth, feed load, post create) to detect regression during rebase.
Deprecation Flags
Deprecation Flags
Upstream feature flags let you phase into new APIs while old ones still exist.
Risk & Mitigation
| Risk | Impact | Mitigation |
|---|---|---|
| Divergence from upstream | Hard upgrades | Rebase weekly; avoid large refactors in core files |
| Hidden security fix missed | Exposure | Subscribe to repo releases; implement dependabot/security scanning |
| Unbounded scope creep | Maintenance drag | Define exit criteria for each forked change |
| Performance regression | User experience | Profile before/after; keep benchmarks |
Performance Tuning Targets
Render Minimization
Render Minimization
Virtualize long lists; memoize heavy pure components.
Network Layer Adjustments
Network Layer Adjustments
Batch requests, introduce caching headers.
Image Handling
Image Handling
Lazy load & use responsive sources; prefetch critical thumbnails.
Startup Path
Startup Path
Defer non-critical observers until post-first-render.
Security & Compliance
Anti-Patterns
Editing Generated Code
Editing Generated Code
Regenerate or wrap instead; manual edits get lost.
Monolithic Commit of All Changes
Monolithic Commit of All Changes
Hard to review; split into atomic PRs.
Copy-Paste Overriding
Copy-Paste Overriding
Extract shared utility rather than duplicating logic.
Ignoring Upstream Lint/Format
Ignoring Upstream Lint/Format
Guarantees painful rebases later.
Contribution Opportunity
If a customization becomes broadly useful (e.g., accessibility improvement), consider opening an upstream PR instead of maintaining a private delta long-term.Checklist Before Forking
- Confirmed lower customization levels insufficient
- Identified scope & success metrics
- Allocated maintenance owner
- Established rebase cadence (e.g. weekly)
- Added contract tests
Repository Links
Next Steps
Reassess periodically whether parts of your fork can collapse back to vanilla via newly added upstream extension points.