Noor Library (Next.js)
Quran reader with Urdu and English translations, several tafseers per ayah, word grammar,
word-by-word meanings, tajweed colours, Indo-Pak script, recitation player, Mushaf mode,
search, surah quizzes and video lectures.
Built with Next.js 16 (App Router), React 19 and Tailwind CSS v4.
Run it
npm install
npm run dev # http://localhost:3000
npm run build && npm start # production
Node 20.9 or newer is needed.
Deploy to Vercel
- Push this folder to a GitHub repo.
- On vercel.com: Add New → Project, pick the repo, keep the defaults (framework: Next.js).
- Click Deploy. No environment variables are needed.
How it is organised
| Folder | What is in it |
|---|
app/ | Pages (one folder per URL) and API routes in app/api/ |
components/ | React components. AppProvider holds settings, bookmarks and panels; PlayerProvider holds the audio player |
lib/ | Data and helpers. quran.ts talks to the outside APIs (server only, cached for 24 hours); views.ts builds what each page shows |
tests/ | Offline mock API and an end-to-end test |
Pages
| URL | Page |
|---|
/, /juz | Surah and Juz lists |
/surah/2, /surah/2/255 | Reader (the second number jumps to an ayah) |
/juz/30 | Juz reader |
/mushaf/1 … /mushaf/604 | Mushaf, page by page |
/tafseer/2/255, /videos/2/255 | Tafseer page, video lectures tab |
/search?q=mercy&scope=en | Search (scope = ar, ur or en) |
/quiz, /quiz/2/1 | Quiz list, quiz (surah 2, part 1) |
/bookmarks | Bookmarks |
Old links from the single-file site (#/surah/2/255) still work; they redirect.
Settings
Settings are saved in the browser (localStorage) and copied to a small cookie
(noor_settings), so the server can render the chosen translations, script, tajweed and
word-by-word meanings straight away. Bookmarks and "continue reading" stay in the browser
for now. Phase 2 (login) will move them to the user's account.
API routes (used by the browser)
| Route | Returns |
|---|
/api/editions | Translation and tafseer lists |
/api/tafsir/{slug}/{s}/{a} | Tafseer text for one ayah |
/api/word/{s}/{a}?w= | Grammar and meaning of one word |
/api/search?q=&scope= | Search results |
/api/quiz/{s} | Data for building a surah quiz |
Data sources
- Quran text and translations: AlQuran Cloud API
- Indo-Pak text, word meanings: Quran.com API
- Tafseer: spa5k/tafsir_api (jsDelivr) and QuranEnc (Rowwad Translation Center)
- Word grammar: Quranic Arabic Corpus (GNU GPL), via mustafa0x/quran-morphology
- Recitation: islamic.network CDN; word audio: Quran.com CDN
Each source URL can be changed with an environment variable; see .env.example.
Testing (offline)
npm run build
./tests/start-test-server.sh # mock API on :4010, app on :3100
npx playwright install chromium # first time only
node tests/e2e.mjs # about 60 feature checks
node tests/visual.mjs # screenshots of every screen (desktop + phone, light + dark) in /tmp/vis
The mock API uses real Arabic, Urdu and English text for Surah Al-Fatiha (1) and Al-Ikhlas (112),
so fonts and vowel marks can be checked by eye. Other surahs use placeholder words.
connecting-quran
