App Shapes
Purpose: Choose the right app shape before you start coding.
Use this when: You want a very simple answer for SPA only, mobile only, or frontend plus backend.
Do not use this when: You already know your app shape and only need endpoint examples.
Backend required: Depends on the app shape.
Allowed runtimes: Browser apps, mobile apps, Node.js, serverless functions, workers.
Required credentials: client_id always. client_secret only for confidential clients.
Minimal import: @quranjs/api/public and sometimes @quranjs/api/server.
Short Answer
- If you want Content or Search, use a backend and select Backend/server app in Developer Console.
- If you want User APIs only without a backend, select Frontend or mobile app; Developer Console provisions it as a public client.
- If you want both user features and Quran data, build a frontend plus backend app and select Backend/server app.
- Always follow the flow for the app type shown in Developer Console instead of guessing the client type.
Decision Tree
3 App Shapes
| App shape | Typical client type | Backend required? | Can use User APIs? | Can use Content? | Can use Search? | Recommended SDK use |
|---|---|---|---|---|---|---|
| SPA only | Public client | No for OAuth; browser-origin restrictions may still require an API proxy | Yes | No | No | @quranjs/api/public |
| Mobile only | Public client | No | Yes | No | No | @quranjs/api/public |
| Frontend + backend | Confidential client | Yes | Yes | Yes | Yes | app: @quranjs/api/public, backend: @quranjs/api/server |
If You Want This, Build That
| What the client wants | Best app shape | Why |
|---|---|---|
| Quran reader only | Frontend + backend | Reader data comes from the protected Content API |
| Search only | Frontend + backend | Search uses an app token and needs a backend |
| Notes, bookmarks, or collections only | SPA or mobile app using the Frontend or mobile app type; add a proxy if browser-origin rules require one | These are User APIs and use a user token |
| Reader plus bookmarks | Frontend + backend | Reader needs Content and bookmarks need a user session |
| Search plus signed-in user features | Frontend + backend | Search needs an app token and user features need a user token |
| Mobile app with signed-in user features only | Mobile app using the Frontend or mobile app type | Developer Console provisions a public client that uses PKCE without a secret |
Public Client vs Confidential Client
Public client
Think: code running on the user's device.
Select Frontend or mobile app in Developer Console for this client type.
- Browser SPA
- Mobile app
- No safe place to keep
client_secret
Public clients can use:
- PKCE login
- user access tokens
- User APIs like notes, bookmarks, collections, and other signed-in features
Public clients cannot directly use:
client_credentials- Content API
- Search API
- any secret-based OAuth flow
Confidential client
Think: app with a safe backend.
Select Backend/server app in Developer Console for this client type.
- Next.js with server routes
- Express backend
- serverless backend or BFF
Confidential clients can use:
client_secreton the backend- backend code exchange and refresh
- Content API
- Search API
- User APIs
The Two Token Paths
There are two different tokens in this platform:
- User token: for personal actions like notes, bookmarks, collections, and QuranReflect user features.
- App token: for app-level reads like Content and Search.
That is why a frontend-only public client can call some User APIs but cannot honestly call Content or Search directly.
AI and Vibe-Coding Prompt
Use this prompt when you want an AI tool to scaffold the correct integration shape:
Implement Quran Foundation integration using the correct app shape.
Rules:
- If the app needs Content or Search, use frontend + backend.
- If the app is browser-only or mobile-only, use @quranjs/api/public only for PKCE and User APIs.
- Never place client_secret in browser or mobile code.
- Treat User APIs and Content/Search as different token paths.
- User token = notes, bookmarks, collections, QuranReflect user features.
- App token = Content and Search.
- If the app needs both, use @quranjs/api/public in the app and @quranjs/api/server on the backend.
Docs:
- Start here: https://api-docs.quran.foundation/docs/sdk/javascript
- App shapes: https://api-docs.quran.foundation/docs/sdk/javascript/app-shapes
- Runtime matrix: https://api-docs.quran.foundation/docs/sdk/javascript/runtime-matrix
- Auth matrix: https://api-docs.quran.foundation/docs/sdk/javascript/auth-matrix