FreeKiosk Development Guide
March 26, 2026 · View on GitHub
Build, run, and ship FreeKiosk locally
Docs Home • Installation • Roadmap
Table of Contents
- Prerequisites
- Additional Requirements
- Local Setup
- Run on Android
- Common Issues
- Build Release APK
- Output Locations
- Contributing
- How to Contribute
- Related Technical Docs
- Project Structure
Note
This page focuses on contributor setup. Operational deployment is documented in installation.md.
Prerequisites
| Tool | Version | Purpose |
|---|---|---|
| Node.js | 18+ | JavaScript runtime |
| React Native CLI | Latest | Cross-platform development |
| Android Studio | Latest | Android emulator & build tools |
| JDK | 17+ | Java development for Android |
| Git | Latest | Version control |
Additional Requirements
- Android SDK (API level 26+ / Android 8.0+)
- Physical Android device or Emulator for testing
- USB debugging enabled on development device
Local Setup
# Clone the repository
git clone https://github.com/rushb-fr/freekiosk.git
cd freekiosk
# Install dependencies
npm install
# iOS dependencies (if developing for iOS)
cd ios && pod install && cd ..
Tip
Make sure to run pod install after any changes to native dependencies.
📱 Run on Android
# Start Metro bundler
npm start
# In another terminal, run on Android
npx react-native run-android
# Or run on specific device
npx react-native run-android --device <device_id>
Common Issues
| Issue | Solution |
|---|---|
| Metro bundler not starting | Clear cache: npm start -- --reset-cache |
| Build fails | Clean Android build: cd android && ./gradlew clean && cd .. |
| Device not detected | Check USB debugging: adb devices |
Build Release APK
# Navigate to Android directory
cd android
# Build release APK
./gradlew assembleRelease
# Build release AAB (for Play Store)
./gradlew assembleBundle
Output Locations
| Format | Path |
|---|---|
| APK | android/app/build/outputs/apk/release/app-release.apk |
| AAB | android/app/build/outputs/bundle/release/app-release.aab |
Important
For production builds, make sure to configure your signing keys in android/app/build.gradle.
Contributing
| Resource | Link |
|---|---|
| Contributing Guide | CONTRIBUTING.md |
| Issue Tracker | GitHub Issues |
| Discussions | GitHub Discussions |
| FAQ | FAQ |
How to Contribute
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
Related Technical Docs
| Documentation | Focus |
|---|---|
| Install Guide | Installation - Manual setup instructions |
| ADB Configuration | ADB-Configuration - Scripted provisioning |
| REST API | REST-API - HTTP endpoints and automation |
| MQTT | MQTT - Home Assistant integration |
| Roadmap | Roadmap-and-Changelog - Release planning |
Project Structure
freekiosk/
├── src/ # React Native source code
│ ├── components/ # Reusable UI components
│ ├── screens/ # App screens
│ ├── navigation/ # Navigation configuration
│ └── assets/ # Images and resources
├── android/ # Android-specific code
│ ├── app/ # Main Android app
│ ├── gradle/ # Gradle build configuration
│ └── build.gradle # Android build script
├── ios/ # iOS-specific code (if applicable)
├── docs/ # Documentation source
└── __tests__/ # Unit tests