Mukoko News

Pan-African news, in one place.

"Mukoko" means beehive in Shona — where the community gathers and stores knowledge. Mukoko News aggregates hundreds of African newsrooms into one feed, so a reader in Harare can follow Lagos, Nairobi and Dakar without opening twenty tabs.

All 54 African Union member states are in scope. How many are live is a number the app measures rather than asserts — see Coverage.

Version: 4.58.0  ·  Live: news.mukoko.com

Read the news →  ·  Join the Discord →  ·  Contribute →

---

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

# Prerequisites: Node.js 20+, pnpm 10+
git clone https://github.com/mukoko-dev/mukoko-news.git
cd mukoko-news
pnpm install

# Run the test suite — no credentials needed
pnpm test

# Start the dev server (reads from the live API by default)
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             # full suite
pnpm test:watch       # watch mode
pnpm test:coverage    # with coverage report

---

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.

---

Embed widget

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.