`
- Pass `process.env.NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN || ""` as the access token — the `Map` component validates it and shows an error if missing, so examples don't need their own check
- Export the component with a descriptive name (PascalCase)
- Create additional example files for each variation (e.g., `heatmap-color-example.tsx`, `heatmap-custom-example.tsx`)
### Step 5: Create Documentation Page
Location: `src/app/docs/{slug}/page.tsx`
Use the `lines-animated/page.tsx` as the gold standard reference.
The slug should match the sidebar href (e.g., `/docs/heatmap` → `src/app/docs/heatmap/page.tsx`).
```typescript
import { DocsLayout, DocsSection, DocsCode, DocsLink } from "../_components/docs"
import { ComponentPreview } from "../_components/component-preview"
import { CodeBlock } from "../_components/code-block"
import { HeatmapExample } from "../_components/examples/heatmap-example"
import { getExampleSource } from "@/lib/get-example-source"
import { Metadata } from "next"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"
export const metadata: Metadata = {
title: "Heatmap",
}
const HeatmapPage = () => {
const basicSource = getExampleSource("heatmap-example.tsx")
return (
First, make sure you have the base map component installed:
Then install the heatmap component:
{/* Additional sections with examples, props tables, etc. */}
)
}
export default HeatmapPage
```
##### Key rules:
- Always export `metadata` with a `title`
- Use `DocsLayout` with `title`, `description`, `prev`, and `next` navigation links
- First section is always "Installation" with two `CodeBlock`s (base map + component)
- The basic `ComponentPreview` goes directly after Installation (no section title or description, just the demo)
- Use `ComponentPreview` to wrap each example with its source code
- Use `getExampleSource("filename.tsx")` to load example source code
- Use `DocsCode` for inline code references in descriptions
- Use `DocsSection` with a `title` for each section
- Add a props `Table` when the component has many configurable props
- Set `prev`/`next` to match adjacent items in the sidebar navigation
### Step 6: Add to Sidebar
Update `src/app/docs/_components/docs-sidebar.tsx`:
1. Import the Lucide icon at the top (if not already imported)
2. Add a `NavItem` entry in the correct section of the `navigation` array
3. Add `badge: "new"`
```typescript
{ title: "Heatmap", href: "/docs/heatmap", icon: Flame, badge: "new" },
```
Sections:
- `"Explore"` — Story, Changelog
- `"Get Started"` — Introduction, Installation, Comparison, Components, Hooks, Reference
- `"Core"` — Map, Controls, Compass, Marker, Popup
- `"Features"` — Everything else
### Step 7: Add to Components Page
Update `src/app/docs/components/page.tsx`:
1. Import the Lucide icon at the top (if not already imported)
2. Add a `ComponentItem` entry to the `components` array
3. Add `isNew: true`
```typescript
{
title: "Heatmap",
href: "/docs/heatmap",
description: "Short description matching the registry description",
icon: Flame,
category: "features",
installCommand: "npx shadcn@latest add https://www.terrae.dev/heat-map.json",
isNew: true,
},
```
##### Key rules:
- `category` is `"core"` or `"features"` (must match the sidebar section)
- `installCommand` URL follows the pattern `https://www.terrae.dev/{registry-name}.json`
- Add `mapboxOnly: true` if the component only works with Mapbox GL (not MapLibre)
- Place the entry near similar components in the array
### Step 8: Update Changelog
Update `src/app/docs/changelog/page.tsx`:
Add a new entry to the `components` array of the most recent (topmost) `ChangelogEntry` in the `changelogs` array:
```typescript
{
title: "Heatmap",
description: (
<>
New
MapHeatmap component for
visualizing data density on the map. Supports customizable color ramps, radius control,
and intensity adjustment.
),
href: "/docs/heatmap",
},
```
##### Key rules:
- Add under `components` for new components, `features` for new features, `fixes` for bug fixes, `properties` for new props
- The `description` uses JSX with inline `
` tags for component names
- Always include `href` linking to the docs page
### Step 9: Review with User
Before finalizing, show all changes:
- The component source code
- The barrel export addition
- The registry entry
- The example file(s)
- The documentation page
- The sidebar entry
- The components page entry
- The changelog entry