New

Create New Component Skill

End-to-end workflow for building a new Terrae component from scratch.

Covers all 8 outputs:

• Component source
• Registry
• Exports
• Documentation
• Examples
• Sidebar
• Components page
• Changelog

Component structure, patterns, responsiveness, and performance rules are in .claude/rules/react/component.md.

All Outputs

Instructions

When the developer requests a new component:

Step 1: Gather Requirements

Ask for:

• Component name (e.g., MapHeatmap, MapPolygon)
• Core functionality
• Whether it needs compound components (like MarkerContent, MarkerPopup)
• Category: "core" or "features" (most components are features)
• Lucide icon for the sidebar and components page
• Whether it exposes a control hook (e.g., useHeatmapControl)

If there are multiple valid implementation approaches (e.g., Mapbox layers vs DOM overlay, canvas vs CSS animations, GeoJSON source vs custom rendering), present the options with trade-offs and let the developer choose before writing code.

Step 2: Create the Component File and Export

Follow the map component rules in .claude/rules/react/component.md for the component structure, template, patterns, and barrel export.

• Location: src/registry/map/{component-name}.tsx
• Use kebab-case for file names (e.g., heat-map.tsx)
• Export from src/registry/map/index.tsx

Step 3: Add Registry Entry

Update registry.json by adding an entry to the items array.

Follow this structure:

{
  "name": "heat-map",
  "type": "registry:ui",
  "title": "Map Heatmap",
  "description": "Short description of the component.",
  "dependencies": ["mapbox-gl"],
  "devDependencies": ["@types/mapbox-gl"],
  "registryDependencies": ["https://www.terrae.dev/map.json"],
  "files": [
    {
      "path": "src/registry/map/heat-map.tsx",
      "type": "registry:ui",
      "target": "components/ui/map/heat-map.tsx"
    }
  ]
}

Key rules:

• name uses kebab-case with ``prefix (e.g.,heat-map)
• registryDependencies always includes ["https://www.terrae.dev/map.json"] (the core Map component that all other components depend on)
• Add extra dependencies only if the component needs packages beyond mapbox-gl
• Components that don't need mapbox-gl directly can have empty dependencies (e.g., watermark)

Step 4: Create Example File(s)

Location: src/app/docs/_components/examples/{name}-example.tsx

Use kebab-case for the file name.

The basic example should demonstrate the simplest usage of the component.

import { Map, MapHeatmap } from "@/registry/map"

export const HeatmapExample = () => {
  const accessToken = process.env.NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN || ""

  return (
    <div className="h-full w-full">
      <Map accessToken={accessToken} center={[-74.006, 40.7128]} zoom={10}>
        <MapHeatmap id="heatmap-basic" {/* ...minimal props */} />
      </Map>
    </div>
  )
}

Key rules:

• Only add "use client" if the example uses hooks, event handlers, or browser APIs — purely compositional examples that just render map components don't need it
• Import from @/registry/map
• Wrap the map in a <div className="h-full w-full">
• 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).

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 (
    <DocsLayout
      title="Heatmap"
      description="Short description of what the component does."
      prev={{ title: "Previous Component", href: "/docs/previous" }}
      next={{ title: "Next Component", href: "/docs/next" }}
    >
      <DocsSection title="Installation">
        <p>First, make sure you have the base map component installed:</p>
        <CodeBlock code={`npx shadcn@latest add https://www.terrae.dev/map.json`} language="bash" />
        <p className="mt-4">Then install the heatmap component:</p>
        <CodeBlock
          code={`npx shadcn@latest add https://www.terrae.dev/heat-map.json`}
          language="bash"
        />
      </DocsSection>

      <ComponentPreview code={basicSource}>
        <HeatmapExample />
      </ComponentPreview>

      {/* Additional sections with examples, props tables, etc. */}
    </DocsLayout>
  )
}

export default HeatmapPage