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:

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/nyuchi/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

Design system

Mzizi is the source of truth — the palette, the background scale and the type ramp are read from its MCP (mzizi_get_tokens), not defined here. src/app/globals.css holds this app's copy, and src/app/__tests__/design-tokens.test.ts asserts every value against a checked-in Mzizi snapshot, so a drift fails CI rather than shipping.

Seven African Minerals carry the brand; these four are the ones you meet first:

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"
    }
  }
}

No authentication required. The MCP server lives in nyuchi/mukoko-news-gateway.

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.

License

MIT — see LICENSE.

"Ndiri nekuti tiri" — I am because we are

Built by Nyuchi Technologies and open-source contributors.