> ## Documentation Index
> Fetch the complete documentation index at: https://social-b97141fb-auto-generate-llmstxt.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Fork & Extend

> Level 3: Advanced customization with complete source code control

For teams who need **complete control** over UIKit components and user flows. Fork & Extend gives you access to the full source code, allowing unlimited customization freedom.

<CardGroup cols={2}>
  <Card title="Full Source Access" icon="code-fork">
    Complete control over all components
  </Card>

  <Card title="Custom Layouts" icon="grid">
    Build entirely new user flows
  </Card>

  <Card title="Your Codebase" icon="code-branch">
    Maintain your own version and roadmap
  </Card>

  <Card title="Professional Workflow" icon="terminal">
    Full development environment setup
  </Card>
</CardGroup>

<Info>
  Pick Fork & Extend only after validating that <a href="/uikit/customization/dynamic-ui">Dynamic UI</a> and <a href="/uikit/customization/component-styling">Component Styling</a> cannot achieve your goals with acceptable complexity.
</Info>

## 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

<Tip>
  If you expect to contribute improvements back later, maintain a **light fork** (few direct core edits) and use extension points / adapters where possible.
</Tip>

## Repository Directory

| Platform     | Repository                                                                                                                                             | Language / Stack   | Package / Tooling           | Notes                            |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | --------------------------- | -------------------------------- |
| iOS          | [https://github.com/AmityCo/ASC-UIKit-iOS-OpenSource](https://github.com/AmityCo/ASC-UIKit-iOS-OpenSource)                                             | Swift              | SwiftPM                     | SwiftUI wrappers & UIKit interop |
| Android      | [https://github.com/AmityCo/Amity-Social-Cloud-UIKit-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](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](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](https://github.com/AmityCo/Amity-Social-UIKit-Flutter-Opensource)                   | Dart / Flutter     | pub                         | Composable widgets               |

## Forking Strategies

<AccordionGroup>
  <Accordion title="Light Fork (Recommended)">
    Keep upstream directory structure; override via extension hooks, subclassing, dependency injection. Avoid editing core logic; instead patch behavior through public APIs.
  </Accordion>

  <Accordion title="Selective Extraction">
    Copy only needed modules (e.g. feed + reactions) into your mono‑repo, leaving update path harder but reducing dependency surface.
  </Accordion>

  <Accordion title="Heavy Fork">
    Broad internal rewrites; highest divergence risk; only for teams prepared to maintain a private long‑term branch & merge engine changes manually.
  </Accordion>
</AccordionGroup>

## Recommended Workflow

<Steps>
  <Step title="Fork Upstream">Create fork in your org; clone locally.</Step>
  <Step title="Add Upstream Remote">`git remote add upstream <canonical-repo-url>`</Step>
  <Step title="Baseline Audit">Run tests, lint, build to ensure clean starting point.</Step>
  <Step title="Create Feature Branches">One logical customization per branch; keep diffs focused.</Step>
  <Step title="Abstraction First">Add interfaces / adapters before altering core flows.</Step>
  <Step title="Rebase Regularly">`git fetch upstream && git rebase upstream/main` (avoid giant merge commits).</Step>
  <Step title="Tag Internal Releases">Semantic pre-release tags (e.g. `4.2.1-fork.3`).</Step>
</Steps>

## Git Operations (Examples)

<CodeGroup>
  ```bash Add upstream theme={null}
  git remote add upstream https://github.com/AmityCo/ASC-UIKit-iOS-OpenSource.git
  git fetch upstream
  ```

  ```bash Rebase with upstream main theme={null}
  git checkout main
  git fetch upstream
  git rebase upstream/main
  ```

  ```bash Feature branch theme={null}
  git checkout -b feat/custom-channel-flow
  ```

  ```bash Tag internal release theme={null}
  git tag -a v4.2.1-fork.1 -m "Add custom channel retention policy"
  git push origin v4.2.1-fork.1
  ```
</CodeGroup>

## 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   |

<Tip>
  Prefer adding a new extension seam over editing multiple call sites—easier to rebase.
</Tip>

## Upgrade Strategy

<AccordionGroup>
  <Accordion title="Track Upstream Tags">Mirror upstream tags; create merge PRs soon after releases while diff is small.</Accordion>
  <Accordion title="Changelog Diffing">Automate `git diff upstream/vX.Y.Z..upstream/vX.Y.(Z+1)` to surface structural changes.</Accordion>
  <Accordion title="Contract Tests">Write smoke tests for critical flows (auth, feed load, post create) to detect regression during rebase.</Accordion>
  <Accordion title="Deprecation Flags">Upstream feature flags let you phase into new APIs while old ones still exist.</Accordion>
</AccordionGroup>

## 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

<AccordionGroup>
  <Accordion title="Render Minimization">Virtualize long lists; memoize heavy pure components.</Accordion>
  <Accordion title="Network Layer Adjustments">Batch requests, introduce caching headers.</Accordion>
  <Accordion title="Image Handling">Lazy load & use responsive sources; prefetch critical thumbnails.</Accordion>
  <Accordion title="Startup Path">Defer non-critical observers until post-first-render.</Accordion>
</AccordionGroup>

## Security & Compliance

<Checklist>
  <Check>Remove debug logging in production forks</Check>
  <Check>Review 3rd-party dependency versions on each upstream sync</Check>
  <Check>Static analysis / lint passes in CI</Check>
  <Check>Secrets loaded via environment or secure vault, never hard-coded</Check>
  <Check>License headers preserved where required</Check>
</Checklist>

## Anti-Patterns

<AccordionGroup>
  <Accordion title="Editing Generated Code">Regenerate or wrap instead; manual edits get lost.</Accordion>
  <Accordion title="Monolithic Commit of All Changes">Hard to review; split into atomic PRs.</Accordion>
  <Accordion title="Copy-Paste Overriding">Extract shared utility rather than duplicating logic.</Accordion>
  <Accordion title="Ignoring Upstream Lint/Format">Guarantees painful rebases later.</Accordion>
</AccordionGroup>

## 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

<CardGroup cols={3}>
  <Card title="iOS" href="https://github.com/AmityCo/ASC-UIKit-iOS-OpenSource" icon="apple" />

  <Card title="Android" href="https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Android" icon="android" />

  <Card title="Web (React)" href="https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Web-OpenSource" icon="globe" />

  <Card title="React Native" href="https://github.com/AmityCo/Amity-Social-UIKit-React-Native-CLI-OpenSource" icon="react" />

  <Card title="Flutter" href="https://github.com/AmityCo/Amity-Social-UIKit-Flutter-Opensource" icon="flutter" />
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Component Styling" href="/uikit/customization/component-styling" icon="code">Granular overrides</Card>
  <Card title="Theming Basics" href="/uikit/customization/theming-basics" icon="book">Layering & tokens</Card>
</CardGroup>

<Tip>
  Reassess periodically whether parts of your fork can collapse back to vanilla via newly added upstream extension points.
</Tip>