Zarra

Zarra is an Expo / React Native app for building a daily Quran reading habit. It includes daily ayahs, reflections, a journal, tasbih, progress tracking, Quran browsing, audio playback, and Quran Foundation sign-in/preferences.

This README is written for hackathon judges who want to get the project running quickly on a phone.

Quick Start on a Phone

1. Install prerequisites

• Node.js 22 or newer
• npm 10 or newer
• Expo Go on your iOS or Android phone
• A terminal in this project folder

2. Install dependencies

npm install

3. Add environment variables

Create a .env file in the project root. Use the hackathon-provided values for secrets and URLs.

QURAN_CLIENT_ID=your_quran_client_id
QURAN_CLIENT_SECRET=your_quran_client_secret

# Required for native phone builds so the app can reach the API routes.
EXPO_PUBLIC_API_BASE_URL=your_backend_origin

# Quran Foundation OAuth / user preferences.
EXPO_PUBLIC_QURAN_OAUTH_CLIENT_ID=your_public_oauth_client_id
QF_CLIENT_ID=your_qf_client_id
QF_CLIENT_SECRET=your_qf_client_secret
QF_ENV=prelive
EXPO_PUBLIC_QURAN_OAUTH_BASE_URL=https://prelive-oauth2.quran.foundation
EXPO_PUBLIC_QURAN_OAUTH_AUTHORIZE_PATH=/oauth2/auth
EXPO_PUBLIC_QURAN_OAUTH_REDIRECT_URI=your_oauth_redirect_uri
EXPO_PUBLIC_QURAN_OAUTH_SCOPES=openid offline_access preference

Do not commit real .env secrets. Judges should use the separate hackathon environment file or credentials provided with the submission.

4. Start Expo

npm start

5. Open on your phone

Make sure your phone and laptop are on the same Wi-Fi network. Then open Expo Go and scan the QR code from the terminal or browser.

If the LAN QR code does not connect, start Expo in tunnel mode:

npx expo start --tunnel

What to Try

• Complete onboarding and choose a daily ayah target.
• Read today's ayahs and save a reflection.
• Visit Journal to review saved reflections.
• Use Tasbih for dhikr counting.
• Open Progress to see reading and reflection activity.
• Browse Quran, favorite surahs, and open a surah detail page.
• Try audio playback on a verse or surah.
• Sign in with Quran Foundation if valid OAuth credentials are available.

Useful Commands

npm start

Starts the Expo development server.

npm run android

Builds and runs the native Android app.

npm run ios

Builds and runs the native iOS app.

npm run web

Runs the web version as a fallback.

npm run lint

Runs Expo lint checks.

Web Fallback

If judging on a phone is not possible, run:

npm run web

Then open the local URL printed by Expo. On web, API routes can use relative /api/... paths. On native phone runs, EXPO_PUBLIC_API_BASE_URL must point to a reachable backend origin.

Troubleshooting

• Phone cannot connect to Expo: put the phone and laptop on the same network, or use npx expo start --tunnel.
• Native app shows a missing API base URL error: set EXPO_PUBLIC_API_BASE_URL in .env.
• Quran data, audio, sign-in, or preferences fail: confirm the Quran API and OAuth credentials are present in .env.
• OAuth does not return to the app: confirm EXPO_PUBLIC_QURAN_OAUTH_REDIRECT_URI matches the configured redirect URL for the OAuth client.
• Dependencies behave strangely after switching branches: delete node_modules, then run npm install again.

Tech Stack

• Expo 54
• Expo Router
• React 19
• React Native 0.81
• NativeWind / Tailwind CSS
• Quran Foundation APIs