An open-source Quran reader built with modern web technologies, featuring a 3D page-flipping mushaf layout, multiple translations, and integrated audio recitations.
Explore the Live Demo »
View Features
·
Report Bug
·
Request Feature
Table of Contents
Building a high-quality, performant, and accessible web-based Quran reader. The project emphasizes a clean UI/UX, robust state management, and separation of concerns to provide a seamless reading experience.
- 3D Page-Flipping: GPU-accelerated page turning powered by
react-pageflip. Pages auto-scale to the viewport (single card on mobile, double spread on desktop). - Integrated Audio Engine: Stream Quran recitations seamlessly via the HTML5 Audio API, including play/pause, time scrubbing, and verse-highlight synchronization.
- Incremental Data Prefetching: Zero-latency browsing. Upcoming Surahs are fetched silently in the background and cached before you flip the page.
- Internationalisation (i18n): Full English and Turkish support. UI language switches instantly without reloads and persists across sessions.
- Shareable Read State: Reading state (Surah ID, page number, translator) is synced to the URL, making every session directly shareable.
- Security & Accessibility: All Quran texts and annotations are XSS sanitized via
DOMPurify. The app is completely accessible and responsive.
A production-grade reactive core optimized for speed, safety, and accessibility.
graph TD
A[Vite Dev Server] --> B[React-Router-Dom v7]
B --> C[App.tsx Root]
C --> D[Header / Sidebar]
C --> E[Reading Views]
E --> E1[DetailLayout / VerseCard]
E --> E2[BookLayout / FlipBookContent]
C --> F[Redux Toolkit Store]
F --> F1[Slices: ui · quran · search · translations]
F --> F2[RTK Query: quranApi]
F2 --> G[Açık Quran API]
- RTK Query & Global State: All async data fetching is delegated to Redux Toolkit Query with automatic caching and duplicate request consolidation.
- Code Splitting & Lazy Loading: Heavy views are dynamically split via React
lazy()+<Suspense>, optimizing initial LCP metrics. - Modular UI Architecture: Sub-panels manage their own business logic in isolation to prevent unnecessary parent re-renders.
- Layout Cache & Memory Management: Arabic glyph width measurements are cached and auto-evict at 5,000 entries to prevent unbounded memory growth.
Built on Separation of Concerns and Clean Architecture principles — strict 500-line file ceiling, fully modular.
Click to expand directory tree
src/
├── api/ # Core API communication
│ ├── quranApi.ts # Fetch-based wrappers (Search, Author, Surah)
│ └── types.ts # Domain TypeScript interfaces
│
├── components/
│ ├── audio/
│ │ └── SidebarAudioPlayer.tsx # Playback & player control panels
│ ├── book/
│ │ ├── flip-book/ # 3D / flat page-flip layout
│ │ │ ├── components/ # Mobile & desktop UI elements
│ │ │ ├── hooks/
│ │ │ │ ├── mushafPagination.ts # Text-width measuring & dynamic layout engine
│ │ │ │ └── useFlipBook.ts # Viewport scaling & zoom controller
│ │ │ ├── DesktopFlipBook.tsx # 3D/flat page-flipping view (desktop)
│ │ │ ├── FlipBookContent.tsx # Responsive view bridge switcher
│ │ │ └── MobileFlipBook.tsx # Fluid single-page scroll view (mobile)
│ │ └── layout/ # Scroll-reading layouts & actions
│ └── ui/ # Base UI elements
│
├── hooks/ # Shared custom React hooks
│ ├── useAudioPlayer.ts # HTML5 Audio (play, pause, seek, duration)
│ ├── useBookLayoutPagination.ts # Book layout index navigation
│ ├── useBookLayoutRoutingSync.ts # Syncs read state with URL parameters
│ └── useQuranSearch.ts # Debounced search & routing coordinator
│
├── store/ # Redux Toolkit global state
│ ├── services/
│ │ └── quranApi.ts # RTK Query endpoints with automatic caching
│ ├── slices/ # ui, quran, search, translations
│ └── store.ts # Store config & middleware
│
├── translations/
│ └── index.ts # i18n dictionary — English & Turkish
│
├── App.tsx # Root & incremental sync coordinator
└── main.tsx # React DOM entry point
To get a local copy up and running, follow these simple steps.
Ensure you have the following installed:
- Node.js: v18.0.0 or higher
- npm or yarn
-
Clone the repo
git clone https://github.com/0memo07/Quran-Web-Application.git cd Quran-Web-Application -
Install NPM packages
npm install # or: yarn install -
Start the dev server
npm run dev # → http://localhost:5173 -
Build for production
npm run build # Compile TypeScript & bundle assets npm run lint # Enforce code quality npm run preview # Preview production build locally
Open-source and welcoming. Bug fixes, new features, documentation improvements — all are appreciated! Contribute & Star buttons are embedded directly in the app header and sidebar for easy access.
- Fork the Project
git checkout -b feature/your-feature-name
- Implement your changes
- Keep files under 500 lines (Separation of Concerns).
- Maintain CRLF (Windows) line endings.
- Validate before opening a PR
npm run build && npm run lint - Commit your Changes
git commit -m 'feat: describe your change clearly' - Push to the Branch
git push origin feature/your-feature-name
- Open a Pull Request
| Rule | Detail |
|---|---|
| File size | Keep files under 500 lines |
| Line endings | CRLF (Windows) across all files |
| Branch naming | feature/your-feature-name |
| Before PR | Always run npm run build && npm run lint |
| Issues first | Open an issue to discuss ideas before implementing |
Distributed under the MIT License. See the LICENSE file for more information.