The sibling repos. This one is the reader-facing web app. The
gateway is the public API and MCP server;
the pipeline does the ingestion and
enrichment. Issues land in whichever repo owns the code.
What is this?
This repository is the Next.js 15 frontend for Mukoko News, deployed on Vercel. It is one part of a three-repo platform:
| Repo | Role |
|---|
mukoko-dev/mukoko-news (this repo) | Web frontend — Next.js 15, Vercel |
mukoko-dev/mukoko-news-gateway | Public API + MCP server — Cloudflare Workers |
mukoko-dev/mukoko-ingestion-pipeline | Data pipeline — Fly.io + Cloudflare |
The frontend reads news data directly from MongoDB Atlas via Next.js Server Actions.
Features
- Pan-African coverage — see Coverage for what that claim means
- Discover — browse by country, category, or source
- NewsBytes — TikTok-style vertical swipe feed for quick headlines
- Search — full-text search across all articles
- Dark mode — respects system preference
- Embed widgets — drop a news feed into any site with one
<script> tag
- MCP server — AI assistants can query Pan-African news at
news.mukoko.dev/mcp
- Accessible — Radix UI primitives, WCAG AAA contrast, Schema.org structured data
Coverage
All 54 African Union member states are in scope. The number that is live is a query, not a constant.
getLiveCoverageAction() counts the countries that actually cleared the publishing bar in
the last 30 days, and coverageFragment(n) / coverageClaim(n) in src/lib/constants.ts
are the only sanctioned wording — every page, meta tag and JSON-LD blurb interpolates one
of them. So a country that starts producing appears on its own, and one that goes quiet
drops off on its own, with no code change and nobody editing a number in a file.
This README deliberately does not print the current figure. A hard-coded count in a
document nothing tests is exactly how the app came to claim "16 African countries" on nine
surfaces that had each drifted apart. src/lib/__tests__/coverage-claim.test.ts enforces
the rule for src/; here it is enforced by not writing one down.
Contributing
We welcome contributions to the frontend — UI improvements, new features, bug fixes, accessibility, tests, and documentation are all fair game. You do not need a database connection to contribute: the whole suite runs against mocked data, and most UI work can be done with the dev server pointed at the live API.
See CONTRIBUTING.md for the full guide, and come say hello in
the Discord — it is the fastest way to get a question
answered or to find out whether someone is already on the issue you picked.
Quick start for contributors
git clone https://github.com/mukoko-dev/mukoko-news.git
cd mukoko-news
pnpm install
pnpm test
cp .env.example .env.local
pnpm dev
Open http://localhost:3000.
What you can work on without credentials
- All React components in
src/components/
- Page layouts and routing in
src/app/
- The embed widget script in
public/embed/
- Any of the unit and integration tests — they all mock the data layer
- Documentation and accessibility improvements
Running tests
pnpm test
pnpm test:watch
pnpm test:coverage
Tech stack
| Layer | Technology |
|---|
| Framework | Next.js 15, App Router, React 19 |
| Styling | Tailwind CSS 4, CSS variables |
| Components | Radix UI (accessible primitives) |
| Icons | Lucide React |
| Theme | next-themes |
| Auth | WorkOS AuthKit |
| Data | MongoDB Atlas via Server Actions |
| Tests | Vitest, React Testing Library |
| Deploy | Vercel |
Design system
Mzizi is the upstream source for the palette, the background
scale and the type ramp. Be precise about how that binding works, because it is looser
than "read from Mzizi" suggests:
src/app/globals.css holds this app's copy of the values. Nothing is fetched at build
time or at runtime — there is no Mzizi package dependency and no network call.src/app/__tests__/design-tokens.test.ts parses that stylesheet and asserts every
value against a SNAPSHOT object literal inside the test file itself. There is no
separate snapshot artefact.- That snapshot is a copy of what
mzizi_get_tokens returned on a dated, recorded
refresh. It is updated deliberately, by a human re-querying the MCP in a reviewed
change — never by relaxing an assertion.
So CI catches globals.css drifting away from the frozen copy. It does not catch
Mzizi itself moving; that is what the deliberate refresh is for.
Mzizi's full palette is 21 colour families — seven minerals, seven heritage, seven
experimental. This app uses the seven minerals; these four are the ones you meet
first:
| Role | Light | Dark | Mineral |
|---|
--primary | #4B0082 | #B388FF | Tanzanite |
--secondary | #0047AB | #00B0FF | Cobalt |
--success | #004D40 | #64FFDA | Malachite |
--surface | #EEEEEC | #131211 | (Mzizi surface — a background step, not a mineral) |
Fonts: Noto Serif (display/headings), Noto Sans (UI/body), JetBrains Mono
(data and labels) — self-hosted via next/font.
Add a Mukoko News feed to any website:
<script src="https://news.mukoko.com/embed/widget.js"
data-layout="cards"
data-feed="latest"
data-country="ZW">
</script>
Layouts: cards · compact · hero · ticker · list
Feeds: top · featured · latest · location
Country: any ISO 3166-1 alpha-2 code (e.g. ZW, KE, ZA, NG)
MCP server
AI assistants and agents can query Pan-African news via the Model Context Protocol:
{
"mcpServers": {
"mukoko-news": {
"type": "http",
"url": "https://news.mukoko.dev/mcp"
}
}
}
The read tools answer anonymously. The server itself lives in
mukoko-dev/mukoko-news-gateway and is
deployed to news.mukoko.dev, not to this app — news.mukoko.com serves no /mcp
route.
Project structure
src/
├── app/ # Pages (Next.js App Router)
├── components/
│ ├── ui/ # Primitives (Button, Card, Skeleton, ErrorBoundary, …)
│ ├── layout/ # Header, footer, mobile nav
│ └── *.tsx # Feature components (ArticleCard, HeroCard, ShareModal, …)
├── contexts/ # PreferencesContext, CoverageContext (theme via next-themes)
└── lib/
├── actions/ # Server Actions — all database reads go through here
├── mongodb/ # MongoDB query helpers
├── constants.ts # Countries, categories, URL utilities
└── utils.ts # Formatting + security helpers
public/
└── embed/ # Self-contained widget script
Security
We take security seriously. Report vulnerabilities by email to security@nyuchi.com — please do not open a public GitHub issue. See SECURITY.md for details.
Licence
This repository ships no LICENSE file, and package.json declares no license
field. Despite the wording below, no licence is currently granted — a LICENSE file
needs adding before the "open-source contributors" framing is accurate.
© Nyuchi Africa (PVT) Ltd.
"Ndiri nekuti tiri" — I am because we are
Built by Nyuchi Web Services and contributors.
