Repository navigation
Mobile App Development
Floppy is building native iOS and Android apps using React Native and Expo, and contributions are welcome!
Whether you're an experienced mobile developer or someone who has never worked with Expo before, this guide will help you get started.
You don't need to understand the entire Floppy codebase to contribute. You can start by running the app, exploring what's implemented, and finding something you'd like to improve.
Floppy's native apps are still in active development. They haven't been published to the App Store or Google Play, and they aren't available through TestFlight or Google's app testing tracks.
For everyday use, Floppy remains available as a Progressive Web App (PWA). You can install it directly from your browser.
For development, you can run the native project using Expo Go on a compatible iPhone or Android device, or an iOS Simulator or Android Emulator on your computer.
The native apps are works in progress. Some features already use shared React Native components, while others are incomplete or still being migrated. You may encounter missing functionality or unfinished interfaces.
The goal is to build genuine native clients, not simply wrap Floppy's website in an app.
Expo is a development platform for React Native. It makes it possible to run and work on mobile applications without having to build an installable app package every time you change something.
Expo Go is particularly useful when getting started: it lets you open a compatible development project on your phone and see changes as you work.
- Git, to download the repository and contribute changes.
- Node.js, preferably the current supported LTS version, which includes npm.
- Expo Go, if you're using a physical phone.
- Xcode on macOS for the iOS Simulator, or Android Studio for an Android Emulator.
You don't need every tool. If you only want to work with an Android device, for example, you don't need Xcode.
If you've never installed these before, the Expo environment setup guide walks through the options.
Open a terminal and run:
git clone https://github.com/dannyvfilms/Floppy.git
cd Floppy/native-proof
npm ciThis downloads Floppy and installs the dependencies for the native development project.
The native-proof name comes from the project's original proof of concept. It's now the working location for Floppy's native development.
You don't need to create a new Expo project. Everything required for Floppy's existing project is already in the repository.
From the native-proof directory, run:
npx expo start --lanExpo starts a development server, sometimes called Metro. Your terminal should display a QR code and options for opening the project.
Keep this terminal running while you're developing.
iPhone or iPad
Install Expo Go on your device and connect it to the same local network as your computer. Open your project through Expo Go using the QR code or project link.
If Expo asks you to sign in, use the same Expo account in the CLI and Expo Go.
Android phone or tablet
Install Expo Go from Google Play. Connect your phone and development computer to the same local network, then scan the QR code displayed in your terminal.
iOS Simulator (macOS)
Install Xcode and the necessary iOS Simulator runtime. Start the Simulator, then press i in the Expo terminal.
Android Emulator (Windows, macOS, or Linux)
Install Android Studio, create an Android Virtual Device, and start the emulator. Press a in the Expo terminal to open the project.
Expo Go must support the Expo SDK version used by the checked-out project. If you encounter a version mismatch, check Expo's setup documentation before changing dependencies.
The native app uses Floppy's existing backend. You can open its development interface without having a Floppy server running, but testing actual library data, authentication, and most functionality requires a reachable server.
You can use an existing Floppy development instance or run the backend locally using the contributing guide.
When the app asks for a server address, enter an address the device or simulator can reach.
For example, if your computer is running Floppy on port 8000 and has the local IP address 192.168.1.50, you might use:
http://192.168.1.50:8000
Replace that example address with your computer's actual address.
Remember that localhost on a physical phone refers to the phone itself, not your development computer. Your backend also needs to listen on an accessible network interface, and your firewall must permit the connection.
Use a trusted development environment and test account. Don't expose a debug server to the public internet.
Once connected, sign in and explore the available screens.
Open the Floppy repository in your preferred code editor.
Try something small: adjust a label, fix a spacing issue, or inspect how an existing component works.
Expo normally refreshes the app as you save your changes, so you can see the result on your device without repeatedly rebuilding the application.
Not every change requires native-specific code. Floppy shares UI components across its browser and native interfaces, so some improvements benefit both.
If you've reached this point, you've successfully set up Floppy for mobile development!
Floppy uses a Django backend with an incrementally modernized React interface. Its mobile development follows a shared-component architecture using React Native primitives and React Native Web.
The main areas you'll encounter are:
-
native-proof/— Expo application, screens, navigation, native adapters, and mobile transport. -
frontend/— Shared React and React Native presentation components, along with browser-specific adapters. -
src/— Django backend, APIs, permissions, business logic, and the existing web application.
Shared presentation should remain platform-independent wherever practical. Platform-specific behavior belongs in adapters, with separate implementations when iOS, Android, and the web genuinely need different behavior.
The backend remains authoritative for user data, authentication, permissions, and business rules.
A native implementation does not need to look or behave identically to the browser implementation when platform conventions justify a difference. It should, however, preserve feature behavior and avoid unnecessary duplication.
Floppy maintains a register of its UI migration progress, including components that are fully migrated, partially implemented, or still using legacy interfaces.
Start with the UI component register to identify work. The source map identifies related files, while the architecture registry tracks platform-specific verification.
You can also browse open GitHub issues for bugs, enhancements, and existing discussions.
Useful contributions aren't limited to migrating entire screens. Fixing an interaction, improving accessibility, resolving an Android-specific layout problem, or testing an existing component on another device can all help.
Before starting a large rewrite, check for related issues and existing work so you don't duplicate another contributor's efforts.
Floppy supports sharing most presentation and business logic while allowing iOS- and Android-specific implementations where appropriate.
React Native supports platform-specific filenames such as .ios.jsx, .android.jsx, .native.jsx, and .web.jsx. Use the existing project conventions rather than introducing a parallel implementation unnecessarily.
Device-specific interfaces, including foldable layouts and native navigation behavior, should be developed through the appropriate platform boundary without compromising the shared components.
The goal is consistent functionality with interfaces that feel appropriate to each device.
From the repository root, useful checks include:
npm run check:ui-architecture
python3 scripts/check_ui_docs.pyFor native transport tests, run this from native-proof/:
npm run test:transportYou can also check that Expo can bundle the project:
npx expo export --platform allA successful build isn't the same as testing the app on a device.
When contributing, explain which platforms you actually tested, what interactions you exercised, and what remains unverified. Include screenshots or recordings for visible changes.
Changes intended for both iOS and Android should be checked on both platforms whenever possible. If you only have access to one, state that clearly rather than claiming cross-platform verification.
Floppy welcomes contributions, including AI-assisted development.
Create a branch from latest, keep your change focused, and submit a pull request targeting latest. Follow the repository's contribution guidelines, including its PR template, testing requirements, and AI-assistance disclosure rules.
Explain what you changed, why it helps, and how you tested it. Screenshots and concise reproduction steps are especially useful for mobile UI contributions.
Expo Go can't open the project
Make sure the development server is running, your phone and computer can communicate, and your version of Expo Go supports the project's SDK. On physical iOS devices, also check whether Expo CLI and Expo Go need the same account sign-in.
If local networking prevents Expo from connecting, try npx expo start --tunnel. This may require additional setup and can be slower than LAN mode.
The iOS Simulator or Android Emulator won't start
Check that the corresponding platform tools are installed and a simulator or emulator has been created. iOS Simulator requires macOS and Xcode. Android Emulator requires a configured Android Virtual Device.
Floppy opens, but can't connect to the server
The Expo development server and the Floppy backend are separate processes. Make sure the backend is running, the server URL is reachable from the device, and the correct port is being used.
Something works on the web but not on mobile
This may be an unfinished migration rather than a problem with your environment. Check the existing component register and GitHub issues. If the problem isn't already tracked, report the behavior, device or simulator details, and steps to reproduce it.
If you're unsure where to begin, you don't need to figure everything out alone.
Join the Floppy Discord to talk through development questions, or open a GitHub issue for a reproducible problem.
Contributions of all sizes are welcome. You don't have to build an entire screen to help move Floppy forward.