Quickstart

Get your own incident map deployed and running in under 5 minutes. No coding required.

What You'll Need

1. A GitHub account (free)
2. A Vercel account (free tier works great)
3. A Mapbox account (free tier includes 50,000 map loads/month)

Step 1: Get Your Mapbox Token (1 minute)

1. Go to mapbox.com and sign up or log in
2. Navigate to your Access Tokens page
3. Copy your Default public token (starts with pk.)

Step 2: Deploy to Vercel (2 minutes)

Click the button below to deploy:

This will:

• Fork the repository to your GitHub account
• Set up a new Vercel project
• Prompt you for your Mapbox token

Step 3: Configure Environment (30 seconds)

When Vercel prompts you for environment variables:

1. Paste your Mapbox token as NEXT_PUBLIC_MAPBOX_TOKEN
2. Click Deploy

Wait about 2 minutes for the build to complete.

Step 4: View Your Map (30 seconds)

Once deployed:

1. Click the Visit button to see your live map
2. You should see the demo data with sample incidents
3. Try zooming, panning, and clicking on markers

Congratulations! You now have your own incident map running.

Next Steps

Add Your Own Data

Replace the demo data with your incidents:

1. Go to your GitHub repository (created during deployment)
2. Navigate to public/data/demo.json
3. Edit the file with your incident data
4. Commit the changes - Vercel will automatically redeploy

Minimal incident format:

{
  "incidents": [
    {
      "id": "my-incident-001",
      "status": "published",
      "createdAt": "2024-01-15T00:00:00Z",
      "updatedAt": "2024-01-15T00:00:00Z",
      "temporal": {
        "date": "2024-01-15",
        "dateCertainty": "exact"
      },
      "location": {
        "name": "Phoenix, Arizona",
        "country": "United States",
        "longitude": -112.074,
        "latitude": 33.4484,
        "siteType": "urban"
      },
      "classification": {
        "incidentType": "sighting"
      },
      "summary": "Description of what happened."
    }
  ]
}

See Data Specification for all available fields.

Customize Branding

Edit map.config.ts in your repository:

const config: Partial<MapConfig> = {
  branding: {
    name: 'Your Organization Name',
    description: 'Your map description',
    // logo: '/your-logo.png',
  },
  // ... other settings
};

Use a Template

We provide pre-configured templates for common use cases:

• Aviation Safety - For pilot reporting organizations tracking airspace incidents
• Military & Security - For defense and national security organizations tracking incursions at sensitive facilities
• Historical Research - For researchers and academics studying documented cases and scientific investigations

Copy a template's map.config.ts to your project root.

Add a Custom Domain

1. Go to your Vercel project settings
2. Click Domains
3. Add your custom domain
4. Update your DNS as instructed

Enable More Features

Edit map.config.ts to enable additional controls:

controls: {
  timeline: { enabled: true },     // Time playback
  filters: { enabled: true },      // Filter sidebar
  stats: { enabled: true },        // Stats panel
  incidentFeed: { enabled: true }, // Right sidebar list
},

Starter Data Files

We provide starter data files to help you get started:

Copy minimal-starter.json to start with a clean slate:

cp public/data/minimal-starter.json public/data/my-data.json

Then update your map.config.ts to point to your new file:

dataSources: [
  {
    id: 'my-data',
    name: 'My Incidents',
    adapter: 'static',
    adapterConfig: {
      path: '/data/my-data.json',
    },
    enabled: true,
  },
],

Troubleshooting

Map shows blank gray area

Your Mapbox token is missing or invalid.

• Check the NEXT_PUBLIC_MAPBOX_TOKEN environment variable in Vercel
• Make sure you're using a public token (starts with pk.)

"No incidents to display"

Your data file isn't loading.

• Check that the file path in map.config.ts matches your data file location
• Verify your JSON is valid (use a JSON validator)

Changes aren't showing

Vercel caches aggressively.

• Wait a minute and hard-refresh your browser (Ctrl/Cmd + Shift + R)
• Check Vercel dashboard to ensure the deployment completed

Need Help?

• Read the Troubleshooting Guide for common issues
• Check the FAQ for frequently asked questions
• Review the Configuration Reference for all options
• Read the full Development Guide
• Check the Architecture docs
• Open an issue on GitHub

Related Guides

• Data Sources — Connect to Supabase, APIs, or static files
• Customization — Customize branding, themes, and renderers
• Examples & Recipes — Real-world implementation patterns
• Deployment — Deploy to Vercel, Netlify, or self-host