Skip to content

armgit / mapcn

Public Imported from GitHub
0

Beautiful map components. 100% Free, Zero config, one command setup.

TypeScript
4.7 KB
Raw Blame

AGENTS.md

Project Overview

mapcn is a free, open-source library of ready-to-use, customizable map components for React. Built on MapLibre GL, styled with Tailwind CSS, works seamlessly with shadcn/ui.

The repo serves dual purpose: the core map component registry (src/registry/) and the documentation site at mapcn.dev.

Tech Stack

  • Framework: Next.js 16 (App Router, React 19)
  • Language: TypeScript (strict)
  • Styling: Tailwind CSS v4, shadcn/ui, Radix UI
  • Map Engine: MapLibre GL JS v6
  • Fonts: Geist (sans) + Geist Mono
  • Code Highlighting: Shiki (dual light/dark theme)
  • Registry: shadcn CLI for building distributable components

Project Structure

src/
├── app/
│   ├── layout.tsx                    # Root layout (fonts, metadata, providers)
│   ├── (main)/                       # Main layout group (header + content)
│   │   ├── layout.tsx                # Header wrapper
│   │   ├── (home)/                   # Landing page
│   │   │   └── _components/          # Homepage examples grid
│   │   ├── docs/                     # Documentation pages
│   │   │   └── _components/          # Docs layout, sidebar, TOC, code blocks
│   │   └── blocks/                   # Full-page block demos
│   └── (view)/                       # Standalone block viewer
├── components/                       # Shared app components (header, footer, logo, nav)
│   └── ui/                           # shadcn/ui primitives
├── registry/                         # Core map components (the library itself)
│   ├── map.tsx                       # Main map component + all sub-components
│   └── blocks/                       # Full-page block examples
├── lib/                              # Utilities, navigation config, helpers
└── styles/
    └── globals.css                   # Theme tokens, animations, base styles

Key Conventions

Components

  • Use functional components with named exports
  • Prefer React Server Components; use "use client" only when Web APIs are needed
  • Structure files: exported component → subcomponents → helpers → static content → types
  • Use cn() from @/lib/utils for conditional class merging

Styling

  • Tailwind utility classes only — no CSS modules, no styled-components
  • Mobile-first responsive design
  • Theme tokens defined as CSS custom properties in globals.css (oklch color space)
  • No hardcoded colors — always use semantic tokens (foreground, muted-foreground, border, etc.)

Registry (src/registry/)

  • map.tsx is the single-file component library containing Map, Marker, Popup, Route, Controls, etc.
  • Blocks live in src/registry/blocks/ — each block is a self-contained page component
  • Registry is built via npm run registry:build using the shadcn CLI

Naming

  • Directories: lowercase with dashes (docs-sidebar, block-preview)
  • Components: PascalCase exports (DocsLayout, PageHeader)
  • Files: kebab-case (command-search.tsx, page-header.tsx)

Navigation

  • All site navigation is centralized in src/lib/site-navigation.ts
  • Docs sidebar nav uses docsNavigation, command search uses siteNavigation

Design System

  • Minimal, content-first aesthetic - no visual noise, no unnecessary borders/shadows/decoration
  • Color palette is monochrome (grayscale oklch)
  • Generous, consistent white space; let layouts breathe rather than packing elements tightly
  • Clear typographic hierarchy - Geist Sans for UI/prose, Geist Mono for code/labels; use size, weight, and muted-foreground (not color) to establish hierarchy
  • Header: sticky, backdrop-blur, gradient bottom border
  • Footer: gradient top border matching header

Commands

npm run dev              # Start dev server
npm run build            # Production build
npm run lint             # ESLint
npm run registry:build   # Build distributable registry to public/r/

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.