Installation - Open Mushaf Native

Platform Overview

Open Mushaf Native is available on multiple platforms with various installation methods:

Android

Google Play Store, APK, or build from source

Web / PWA

Browser-based with offline support

iOS

Web app installable to home screen

Build from Source

Full development setup for all platforms

Android Installation

Option 1: Google Play Store (Recommended)

The easiest way to install on Android devices:

Open Play Store

Navigate to the Open Mushaf Native page

Install

Tap the Install button

Launch

Open the app from your home screen or app drawer

Play Store installation provides automatic updates and the most stable experience.

Option 2: APK Installation

For devices without Play Store access:

Download APK

Visit GitHub Releases and download the latest .apk file

Enable Unknown Sources

On your Android device:

Open Settings
Navigate to Security or Privacy
Enable Install from Unknown Sources or Install Unknown Apps
Grant permission to your browser or file manager

Install APK

Locate the downloaded APK file
Tap to open it
Tap Install
Wait for installation to complete
Tap Open to launch

Only download APK files from the official GitHub Releases page. Third-party sources may distribute modified or malicious versions.

Option 3: Build Android from Source

For developers who want to build the APK locally:

Clone Repository

git clone https://github.com/adelpro/open-mushaf-native.git
cd open-mushaf-native

Install Dependencies

npm install

Build APK

For development build:

npm run android:build:preview:local

For production build:

npm run android:build:production:local

The APK will be created in the builds/ directory.

Install on Device

Transfer the APK to your Android device and install it following the APK installation steps above.

iOS Installation

Currently, Open Mushaf Native is available on iOS as a Progressive Web App (PWA):

Open Safari

Navigate to https://open-mushaf-native.web.app/ in Safari browser

Safari is required for PWA installation on iOS. Other browsers don’t support this feature.

Add to Home Screen

Tap the Share button (square with arrow pointing up)
Scroll down and tap Add to Home Screen
Edit the name if desired
Tap Add

Launch App

The app icon will appear on your home screen. Tap it to launch Open Mushaf Native as a standalone app.

The PWA version works offline after the initial load and provides a native-like experience on iOS.

Web Application

Use Open Mushaf Native directly in your browser:

Direct Browser Access

Visit Web App

Open https://open-mushaf-native.web.app/ in any modern browser:

Chrome (recommended)
Firefox
Safari
Edge

Start Using

The app loads instantly and works directly in your browser

Install as PWA (Desktop/Android)

Chrome (Desktop)
Chrome (Android)
Edge (Desktop)

Open Web App

Visit https://open-mushaf-native.web.app/ in Chrome

Install

Look for the install icon (➕) in the address bar
Click Install
The app will open in its own window

Access from Apps

Find the installed app in:

Start Menu (Windows)
Applications folder (macOS)
Chrome Apps (chrome://apps)

PWA installation provides:

Standalone app window without browser UI
App icon in your system’s app launcher
Offline functionality
Faster startup time

Building from Source

For developers who want to run, modify, or contribute to the project:

System Requirements

Node.js

Version 22 or higher required

Expo SDK

Version 54 (installed automatically)

Platform Tools

Android Studio (Android) or Xcode (iOS/macOS)

Git

For cloning the repository

Development Setup

Install Node.js

Download and install Node.js v22+ from nodejs.orgVerify installation:

node --version  # Should show v22.x.x or higher
npm --version

Clone Repository

git clone https://github.com/adelpro/open-mushaf-native.git
cd open-mushaf-native

Install Dependencies

npm install

This installs all required packages including:

React Native 0.81
Expo SDK 54
TypeScript
Jotai (state management)
All other dependencies

Start Development Server

npm start
# or
npx expo start

This opens the Expo development tools in your terminal.

Running on Different Platforms

Android
iOS
Web
Expo Go

npm run android
# or with specific device
npm run android -d

Prerequisites:

Android Studio installed
Android SDK configured
Android emulator running or physical device connected
USB debugging enabled (for physical devices)

The -d flag lets you select which connected device or emulator to use.

npm run ios

Prerequisites:

macOS required
Xcode installed
iOS Simulator or physical device
Apple Developer account (for physical devices)

iOS builds can only be created on macOS with Xcode installed.

npm run web

The web version runs at http://localhost:19006 by default.

The easiest way to test on physical devices:

Install Expo Go

Download Expo Go from:

Google Play Store (Android)
App Store (iOS)

Start Dev Server

npm start

Scan QR Code

Android: Scan the QR code with Expo Go app
iOS: Scan with Camera app, then open in Expo Go

Expo Go has some limitations. For full native features, use development builds.

Advanced Build Commands

The project includes several build scripts:

npm run start:clear

Development Tools

Linting

npm run lint
npm run lint:fix

Type Checking

TypeScript type checking runs automatically. Configure in tsconfig.json

Testing

npm test

Health Check

npm run doctor

Project Structure

Understanding the codebase:

open-mushaf-native/
├── app/                    # Application screens (Expo Router)
│   ├── (tabs)/            # Tab-based navigation
│   │   ├── index.tsx     # Main Mushaf screen
│   │   ├── lists.tsx     # Surahs and bookmarks
│   │   └── (more)/       # Settings and more
│   ├── search.tsx         # Search functionality
│   ├── navigation.tsx     # Page/Surah navigation
│   └── tutorial.tsx       # First-run tutorial
├── assets/                # Images, fonts, icons
├── components/            # Reusable React components
├── constants/             # App constants and configs
├── hooks/                 # Custom React hooks
├── store/                 # Jotai state management
├── utils/                 # Helper functions
├── app.json              # Expo configuration
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── eas.json              # EAS Build configuration

Configuration Files

app.json

Main Expo configuration:

{
  "expo": {
    "name": "Open Mushaf",
    "slug": "open-mushaf-native",
    "version": "4.3.0",
    "orientation": "default",
    "newArchEnabled": true,
    "android": {
      "package": "com.adelpro.openmushafnative",
      "playStoreUrl": "https://play.google.com/store/apps/details?id=com.adelpro.openmushafnative"
    }
  }
}

The app uses the new React Native architecture (newArchEnabled: true) for better performance.

package.json

Key dependencies:

{
  "name": "open-mushaf-native",
  "version": "v4",
  "dependencies": {
    "expo": "54.0.30",
    "react-native": "0.81.5",
    "react": "19.1.0",
    "jotai": "^2.12.4",
    "expo-image": "~3.0.11",
    "@gorhom/bottom-sheet": "^5.1.4"
  }
}

Contributing

Want to contribute? Great!

Fork and Clone

Fork the repository on GitHub
Clone your fork locally

git clone https://github.com/your-username/open-mushaf-native.git
cd open-mushaf-native

Create Branch

git checkout -b feature/your-feature-name

Make Changes

Follow the existing code style
Ensure zero ESLint errors
Test your changes thoroughly

npm run lint:fix  # Fix linting issues

Commit and Push

git add .
git commit -m "Add your feature or fix"
git push origin feature/your-feature-name

Create Pull Request

Open a pull request on GitHub with a clear description of your changes

See the full Contributing Guidelines for more details.

Troubleshooting

Common Issues

npm install fails

Solution:

Ensure you’re using Node.js v22 or higher
Clear npm cache:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Android build fails

Solution:

Ensure Android Studio and SDK are properly installed
Set ANDROID_HOME environment variable
Try cleaning the build:

cd android
./gradlew clean
cd ..
npx expo start --clear

iOS build fails (macOS)

Solution:

Ensure Xcode is installed and up to date
Install CocoaPods if needed:

sudo gem install cocoapods

Clean iOS build folder:

cd ios
rm -rf Pods Podfile.lock
pod install
cd ..

Metro bundler issues

Solution: Clear the Metro cache:

npm run start:clear
# or
npx expo start --clear

PWA not installing on iOS

Solution:

Ensure you’re using Safari browser (required for iOS PWA)
Check that you’re on the actual website, not a cached version
Try clearing Safari cache and revisiting

Deployment

For deploying your own instance:

Firebase Hosting
EAS Build

The official web app is hosted on Firebase:

# Install Firebase CLI
npm install -g firebase-tools

# Login to Firebase
firebase login

# Deploy to preview
npm run deploy:preview

# Deploy to production
npm run deploy:live

For distributing mobile builds:

# Android preview build
npm run android:build:preview

# Android production build
npm run android:build:production

# Submit to Play Store
npm run android:submit:production

Resources

GitHub Repository

View source code and issues

Expo Documentation

Learn more about Expo

React Native Docs

React Native documentation

Report Issues

Bug reports and feature requests

Support

Need help with installation?

Open an issue on GitHub
Contact the developer: [email protected]
Check existing issues for solutions

Get Started

Core Features

Guides

Deployment

​Platform Overview

Android

Web / PWA

iOS

Build from Source

​Android Installation

​Option 1: Google Play Store (Recommended)

​Option 2: APK Installation

​Option 3: Build Android from Source

​iOS Installation

​Web Application

​Direct Browser Access

​Install as PWA (Desktop/Android)

​Building from Source

​System Requirements

Node.js

Expo SDK

Platform Tools

Git

​Development Setup

​Running on Different Platforms

​Advanced Build Commands

​Development Tools

Linting

Type Checking

Testing

Health Check

​Project Structure

​Configuration Files

​app.json

​package.json

​Contributing

​Troubleshooting

​Common Issues

​Deployment

​Resources

GitHub Repository

Expo Documentation

React Native Docs

Report Issues

​Support

Build docs developers (and LLMs) love

Platform Overview

Android Installation

Option 1: Google Play Store (Recommended)

Option 2: APK Installation

Option 3: Build Android from Source

iOS Installation

Web Application

Direct Browser Access

Install as PWA (Desktop/Android)

Building from Source

System Requirements

Development Setup

Running on Different Platforms

Advanced Build Commands

Development Tools

Project Structure

Configuration Files

app.json

package.json

Contributing

Troubleshooting

Common Issues

Deployment

Resources

Support