How shopify/flash-list works
Project Type and Purpose
• This is a cross‑platform React Native library (“FlashList”) that provides a performant List component.
• It consists of:
• A JS/TS layer (src/…) exposing the FlashList API to React Native apps
• Native modules for Android (android/src/...) and iOS (ios/Sources/...)
• Example/demo apps under fixture/
• Documentation website under documentation/ and website/
• CI/CD workflows in .github/workflows/
File Structure
• Top‑level directories:
• src/—core JS/TS implementation, utils, specs, benchmarks, tests
• android/—Kotlin/Java code for native view managers, bridge to JS
• ios/—Swift/Obj‑C code for native view managers, bridging header
• fixture/—sample React Native apps (Expo and bare RN) exercising the library
• documentation/ & website/—Docusaurus site and static site
• .github/workflows/—build, test, deploy pipelines
• Config files: package.json, babel.config.js, tsconfig.json, Gemfile for docs
Key Components
a. JS Layer (FlashList package)
• API entry point (FlashList.tsx, AnimatedFlashList.ts, MasonryFlashList.tsx)
• Utilities, viewability manager, layout providers in src/utils, src/viewability
• Native component wrappers (src/native/...) forwarding props to native
• Tests (src/__tests__) and benchmarks (src/benchmark)
b. React Native Bridge
• Auto‑generated Paper bindings under android/src/paper/java/...
• NativeComponent specs in src/specs/
• Bridging code in iOS header (FlatListPro‑Bridging‑Header.h)
c. Android Native Module
• AutoLayoutViewManager.kt, CellContainerManager.kt, FlashListPackage.kt
• Event emitters (BlankAreaEvent.kt)
d. iOS Native Module
• AutoLayoutViewManager.swift, CellContainerManager.swift
• Component view classes (ComponentView.h/.mm)
e. Host App / Examples
• Expo and bare RN examples calling into @shopify/flash-list
f. Documentation Site
• Docusaurus config, Markdown docs, and static site deploy
g. CI/CD
• GitHub Actions: lint, test, build package, deploy website, release
Relationships and Data Flow
• Host React Native App → imports @shopify/flash-list → calls JS API
• JS API → NativeComponent wrappers → React Native Bridge
• Bridge → Android/iOS native managers → native views
• Native modules → emit layout/scroll events → JS viewability manager
• CI pipelines → two paths:
• Build & test JS + native code → publish npm & CocoaPods
• Build docs → deploy to GitHub Pages or Shopify site
Architectural Patterns and Principles
• Layered architecture: JS layer, bridge, native implementation
• Separation of concerns: rendering (native), business logic (JS), configuration
• Reusability: common PlatformHelper code, shared specs, component wrappers
• Test‑driven: Jest for JS, unit/instrumentation tests on native sides
• Documentation as code: Docusaurus site under version control