# quran.com-frontend-next: the Quran.com front end, with a design system and a container

> The quran.com-frontend-next repository is the official source for the Quran.com site, built on Next.js and TypeScript, with a design language system, Storybook stories, Vitest and Playwright suites, and a PM2 based container image. Its most opinionated sections are the ones about contribution norms, and the most interesting engineering detail is the DLS, a shared component library born out of a scalability mistake.

**quran/quran.com-frontend-next** — Frontend build on next.js

- Repository: https://github.com/quran/quran.com-frontend-next
- Website: https://quran.com
- Stars: 1,926 · Forks: 632
- Language: TypeScript
- License: not declared
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/quran-quran-com-frontend-next

## An isomorphic React front end for a site that publishes a lot of text

This is the official source code repository for Quran.com, and the README describes it as the frontend for the site, built on top of Next.js, which it calls a popular framework that takes the trouble and setup of setting up an isomorphic React app. The deployment story in the README is a little dated in its vocabulary, saying the site is deployed on now.sh automatically with automatic generation of builds for pull requests, which is the early name for what became Vercel. What matters for a reader is the shape of the project. It is a single application that renders verses, translations and audio, supports a dozen locales, and has to be fast on the connections its users actually have, which is why the repository carries a Lighthouse configuration, a PWA runtime config, Sentry configuration files for the edge and the server, and a next-sitemap setup. The `data/`, `locales/`, `i18n.json` and `format-locales.sh` set at the root show the content and translation pipeline, and the `docs/` directory holds the project's own documentation.

## Running it locally, and the environment file

The local setup is documented in five steps and there is nothing to configure beyond the environment file. You need the latest nodejs and npm, preferring version 10 or later, and yarn, installed globally with `npm i -g yarn`. Then you clone the repository, run yarn to install the node_modules, and start the app with `yarn dev`, or with `yarn dev -p 8000` if you want a different port, and open localhost:3000 in a browser. The app hot reloads as you change it, since it runs on Next.js. The one configuration step is renaming `env.example` to `env.local`, which is the Next.js convention for a local environment file, and the example file is a good map of the project's external dependencies. It names Sentry with separate client and server switches, Novu for notifications with a backend URL, a socket URL and an app id, Lokalise for translations with an API key and a project id, a Sanity project id, a Tarteel API key, a signature token and a proxy signature token, an allowed origins list, an SSO toggle, and an embed URL for the Ayah embed.

## The DLS, and the mistake that produced it

The Design Language System section is the most instructive part of the README, because it explains a decision by naming the failure that caused it. The project says that one mistake it made previously was treating each component as unique, and that this made the work not scalable. The reasoning it applies is that large companies often develop a design style language that can be used across the app, without the need to create unique components and ensure better consistency across the product, and that they are trying to take a similar approach. The instruction is concrete: if something can be used elsewhere, put it inside the `dls/` directory and create stories for it. That is a simple rule with large consequences, because it moves the review question from whether this component is right to whether it belongs in the shared set. The Storybook setup supports it, with components built inside Storybook and files named `.stories.tsx`, so an engineer can view the work outside the product and test different configurations, and the whole component set is published to a public Storybook site as well.

## A repository wired for many kinds of AI assistant

The root of the repository carries an unusual concentration of assistant configuration directories, with `.agent/`, `.agents/`, `.claude/`, `.codex/`, `.cursor/`, `.windsurf/` and `.opencode/` alongside `AGENTS.md` and `CLAUDE.md`. That is more than one vendor's file, and it suggests a deliberate decision to support several assistants rather than one. The package scripts follow the same idea, with `ai:sync` running a script that synchronises links and `ai:check` running one that checks them, which is the kind of housekeeping that keeps a large documentation surface from rotting. The rest of the repository is conventional and well organised for a project of this size. There are `src/`, `tests/`, `playwright/` and `vitest.config.ts` for the test layers, a `scripts/` directory with deployment, font, sitemap, Lokalise and file organisation helpers, a `configs/` directory, a `Dockerfile` with `build.yml` and `release.yml` for CI, `remotion.config.ts` with a `media-maker` script pair for producing video, and a `server.js` plus `server-http.js` pair for running the app with its own server.

## Testing and linting, layered

The scripts show four distinct quality layers. Unit and component tests run on vitest, with `test` for a single run, `test:watch` for the watch mode, `test:coverage` for the coverage report and `snapshots:update` to refresh the stored snapshots, which matters for a project with a visual regression suite. Integration tests run on Playwright through `test:integration`, with a `playwright/` directory and a `playwright.config.ts` in the root. Linting is split by tool, with eslint over tsx, ts, js and jsx, stylelint over the scss, and prettier for formatting, plus husky for the git hooks through a `postinstall` script. There is a Lighthouse configuration for performance budgets and a `check:source-release-callouts` script that verifies the release callouts in the source. The TypeScript decision is stated in the README, that it was chosen for the sake of type safety, with an instruction to create types where you see fit, and the repository honours that with type declaration files for the untyped modules it pulls in, for global types, for the Next.js environment, for the redux thunk typing and for the module system. The `scripts/ai/check-links.mjs` and `sync-links.mjs` pair adds a fifth layer specific to the documentation surface.

## The production container, and the pm2 process model

The Dockerfile is the clearest statement of how the site runs in production. It starts from node:18-bookworm-slim, installs ca-certificates and pm2 at version 6, and sets the language, the production environment, the host to 0.0.0.0 and the port to 80. The dependency install is deliberate, since only the package manifest and the yarn lockfile are copied first, and the install runs with `--frozen-lockfile` for consistency, with a comment explaining that `NODE_ENV` is temporarily set to development so that the build's dev dependencies are present. The application is then built, and the environment file is turned into a shell script at build time with an export prefix so that the runtime can source it. The final command sources that script and runs the HTTP server under pm2 with the maximum number of instances and a memory restart threshold of 512 megabytes, which is a useful detail, because a Node service that leaks is restarted rather than taking the container down. The application port is exposed and the base image matches the `engines` field in the package manifest, which asks for Node 18.

## Contribution norms, licences and the state of the repository

The README has a section that most open source projects do not have, and it is worth quoting rather than paraphrasing. It says the project trusts that you will not copy the idea or the project, that this is at the end for the sake of Allah and that everyone has good intentions while working on the project, and then it stresses that copying the code or the project is unacceptable. The header comment at the top of the README says the same thing in a different register, asking contributors to fork and open a pull request or an issue tagged enhancement. In other words, the code is public for contribution and for reading, and the project is not for being cloned. The licence situation is a little muddled, since the README badge points at a LICENSE.txt file and the package manifest declares MIT, while the repository metadata classifies the licence as one it cannot categorise, so the file is the thing to read. Support runs through GitHub issues, with the README pointing new contributors at the issue tracker as a good place to start, and a Discord community for everything else. The last push was on 2026-04-27, while the newest tag, v0.0.12, is from 2025-03-29, so the branch is active but the releases are not, which tells you the project is developed on `production` and tagged rarely. Localisation deserves a credit too, since the README says it was made possible with the help of Lokalise, a computer aided translation system.

## Conclusion

Adopt this repository as a reference if you are building a large content site with an editorial and a design team, since the DLS approach and the Storybook discipline are the transferable parts, and if you want a Next.js setup that ships Playwright integration tests and a production container. Do not adopt it as a general starter, since it is tied to Quran.com's own services, its Lokalise workflow, its Sentry and Novu configuration and its own content pipeline. Before you start, read the contribution section carefully, because the README is unusually direct about what it expects from anyone who works on the code, and note that the tagged releases are old even though the branch is active. The licence is MIT, the last push was on 2026-04-27, and the newest tag is v0.0.12 from 2025-03-29.

## FAQ

### How do I run the Quran.com frontend locally?

Install Node and npm, preferably version 10 or later, install yarn with `npm i -g yarn`, clone the repository, run `yarn` to install the dependencies and then `yarn dev`, or `yarn dev -p 8000` for a different port, and open localhost:3000. Rename `env.example` to `env.local` first, and the app hot reloads as you edit.

### What is the DLS in this repository?

A Design Language System. The README explains it as a response to a previous mistake, treating every component as unique, which made the work unscalable. The rule is that if a component can be used elsewhere it belongs in the `dls/` directory with stories written for it, and the components are developed inside Storybook with `.stories.tsx` files.

### What testing tools does the project use?

Vitest for unit and snapshot tests, with a coverage mode and a snapshot update script, and Playwright for integration tests through `test:integration`. Linting is split between eslint for the code, stylelint for the styles and prettier for formatting, with husky providing the git hooks and a Lighthouse configuration for performance checks.

### How is the site run in production?

The Dockerfile is based on node:18-bookworm-slim with pm2 installed globally, dependencies installed from a frozen yarn lockfile, and the build run with `NODE_ENV` temporarily set to development. The runtime sources a generated environment script and starts the HTTP server under pm2 with the maximum number of instances and a 512 megabyte memory restart threshold, listening on port 80.

## Sources

- [Issues](https://github.com/quran/quran.com-frontend-next/issues)
- [Project website](https://quran.com)
- [quran/quran.com-frontend-next on GitHub](https://github.com/quran/quran.com-frontend-next)
- [README](https://github.com/quran/quran.com-frontend-next/blob/production/README.md)
- [Releases](https://github.com/quran/quran.com-frontend-next/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/quran-quran-com-frontend-next