The Problem

Web teams that need interactive maps often stitch together raw MapLibre code, Tailwind styles, and custom UI logic. The result is duplicated boiler‑plate, hard‑to‑navigate component trees, and fragile builds that lack automated testing.

What This Does

mapcn ships a ready‑made collection of React/Next.js components that wrap MapLibre GL with Tailwind and shadcn/ui primitives. The core UI lives under src/components/ui/ (e.g., button.tsx, sidebar.tsx). Map‑specific logic is in src/registry/map.tsx and the example pages under src/app/docs/_components/examples/. The home page (src/app/(home)/page.tsx) showcases the examples through src/app/(home)/_components/examples-grid.tsx, which pulls in the reusable example-card.tsx component.

How It Is Wired

  1. Next.js server start – npm run dev launches the framework, which reads next.config.ts and builds the route tree from the src/app/ directory.
  2. Home route – HTTP request to / resolves to src/app/(home)/page.tsx. This file renders <Hero /> and <ExamplesGrid />.
  3. Examples grid – src/app/(home)/_components/examples-grid.tsx imports src/app/(home)/_components/examples/index.tsx. The index file re‑exports the individual example components (analytics-example.tsx, ev-charging-example.tsx, …).
  4. Example cards – Each example component composes UI pieces from src/components/ui/ (e.g., <Button />, <Tooltip />) and map helpers from src/lib/ (get-example-source.ts, utils.ts).
  5. Map rendering – The map component itself lives in src/registry/map.tsx. It creates a MapLibre instance, registers sources from public/maps/*.json, and exposes controls defined in src/components/ui/. This file is the widest‑blast module (661 lines) and is imported by many example pages.
  6. Docs sidebars – Documentation pages (src/app/docs/...) import the hub component src/app/docs/_components/docs.tsx, which in turn pulls the highly connected src/app/docs/_components/docs-sidebar.tsx (deep nesting, 6‑level indentation).

The import graph shows 70 internal modules with 54 edges and no circular dependencies. The most connected hub is src/app/docs/_components/docs (10 inbound imports, 1 outbound). Its stability score (0.09) indicates low risk, while modules like src/app/docs/routes/page.tsx have instability 1, meaning they import many others but are not themselves reused.

How To Use It

# clone the repo
git clone https://github.com/moses-y/mapcn
cd mapcn

# install dependencies (npm is the declared package manager)
npm ci

# start the development server
npm run dev   # reads next.config.ts, serves pages under src/app/

No additional configuration files are required; the map tiles are defined in public/maps/registry.json. To customize a tile source, edit that JSON or replace public/maps/map.json with your own provider URL.

Real‑World Use

A SaaS dashboard that needs an interactive location selector can import src/registry/map.tsx directly into a page component:

import Map from '@/registry/map';

export default function LocationPicker() {
  return <Map initialCenter={[‑122.4, 37.8]} />;
}

The component brings built‑in controls, marker handling, and theme awareness without extra setup, letting the team focus on business logic.

Code Health & Issues

  • High – No test suite – 32 source files, zero test files. Adds regression risk.
  • High – No CI pipeline – No workflow runs on push or PR; build and test steps are missing.
  • Medium – Dependabot missing – Only one manifest (package.json), no automated dependency updates.
  • Low – Missing convention files – No .editorconfig, .gitattributes, or formatter config; can cause inconsistent style across contributors.
  • Medium – Deep nesting – src/app/docs/_components/docs-sidebar.tsx has a 6‑level indentation block, making the control flow hard to follow.
  • Medium – Duplicated code – Six‑line blocks repeat across five example components (analytics-example.tsx, ev-charging-example.tsx, etc.).
  • Medium – Oversized files – src/components/ui/sidebar.tsx and src/registry/map.tsx each exceed 600 lines, increasing change‑impact risk.

The Bottom Line

mapcn delivers a functional, zero‑config map UI stack that integrates cleanly with Tailwind and shadcn/ui, making it a solid starting point for front‑end teams. However, the lack of tests, CI, and some code‑base hygiene issues mean you should add a testing harness and refactor the large modules before relying on it for production‑critical features.