Roadmapper

Transform your GitHub issues into beautiful, visual roadmaps

A simple, elegant way to visualize your project roadmap using GitHub issues. Roadmapper automatically generates beautiful SVG roadmaps from your GitHub issues based on labels, making it easy to communicate your project's priorities and timeline.

Website • Live Example • How It Works • Usage

What is Roadmapper?

Roadmapper transforms your GitHub issues into a clean, three-column visual roadmap that's perfect for:

Project README files
Documentation sites
Status pages
Team dashboards

Simply add one of three labels to your GitHub issues—Roadmap: Now, Roadmap: Next, or Roadmap: Later—and Roadmapper does the rest.

Live Example

Here's what this project's roadmap looks like:

💡 Click the roadmap image above to open the interactive viewer where each card is clickable and links directly to its GitHub issue. Due to GitHub's security restrictions, roadmap cards cannot be made clickable when embedded directly in markdown.

Getting Started

Register your repository at roadmapper.rocketstack.co — enter your GitHub owner, repo name, and email to receive your API key.
Confirm your email — click the confirmation link sent to your email. Your key activates after confirmation (the link expires in 24 hours).
Add a .roadmapper file to the root of your repository containing the API key you received. Commit and push.
Label your issues: Add one of these labels to your GitHub issues:
- Roadmap: Now - Top priority items you're working on right now
- Roadmap: Next - Next priority items planned for soon
- Roadmap: Later - Longer-term items under consideration

Embed your roadmap: Use the URL format:

https://roadmapper.rocketstack.co/{owner}/{repo}/{bgColor}/{textColor}

Add to your README: Link to the interactive viewer page where users can click on items:

[![Roadmap](https://roadmapper.rocketstack.co/owner/repo/ffffff/24292f)](https://roadmapper.rocketstack.co/view/owner/repo/ffffff/24292f)

The `.roadmapper` File

The .roadmapper file proves you own the repository and authorizes Roadmapper to generate roadmaps for it. It should contain only the API key you received during registration:

rm_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Place this file in the root of your repository. Roadmapper checks this file periodically (every 24 hours) to verify your registration.

How It Works

Usage

URL Format

https://roadmapper.rocketstack.co/{owner}/{repo}/{bgColor}/{textColor}

Parameters:

owner (required): GitHub repository owner/organization
repo (required): GitHub repository name
bgColor (required): Background color as hex code without # (e.g., ffffff, f6f8fa)
textColor (required): Text color as hex code without # (e.g., 24292f, 000000)

Examples

White background with dark text:

https://roadmapper.rocketstack.co/facebook/react/ffffff/24292f

Dark background with light text:

https://roadmapper.rocketstack.co/facebook/react/0d1117/e6edf3

Light gray background with dark text (GitHub style):

https://roadmapper.rocketstack.co/facebook/react/f6f8fa/24292f

In Your README

Recommended: Interactive Roadmap Link

This shows a preview image that links to a page where each card is clickable:

## Roadmap

[![Roadmap](https://roadmapper.rocketstack.co/your-username/your-repo/ffffff/24292f)](https://roadmapper.rocketstack.co/view/your-username/your-repo/ffffff/24292f)

> Click the roadmap to view the interactive version with clickable cards.

Alternative: Static Image Only

If you just want a static roadmap image without clickable links:

![Roadmap](https://roadmapper.rocketstack.co/your-username/your-repo/ffffff/24292f)

For Documentation Sites (Non-GitHub)

If you're embedding in a website or documentation site that supports HTML, you can use the clickable embed:

<iframe src="https://roadmapper.rocketstack.co/embed/your-username/your-repo/ffffff/24292f" width="100%" height="520" frameborder="0"></iframe>

Or generate HTML code with image maps for more direct embedding (replace rocketstack-matt/roadmapper with your repository).

GitHub Limitation: GitHub's markdown renderer strips iframes and may not support HTML image maps for security reasons. For GitHub READMEs, use the recommended link approach above.

Custom Colors

Roadmapper supports fully customizable colors for your roadmap. You can specify:

Background color (bgColor): Used for the roadmap background and card backgrounds
Text color (textColor): Used for all text, headers, and drop shadows

Colors are specified as hex codes without the # symbol. Both 3-digit and 6-digit hex codes are supported.

Color Examples

Classic light: ffffff/24292f - White background, dark text
GitHub style: f6f8fa/24292f - Light gray background, dark text
Dark mode: 0d1117/e6edf3 - Dark background, light text
Navy: 001f3f/ffffff - Navy background, white text
Forest: 2c5f2d/ffffff - Forest green background, white text

Color Tips

Use high contrast between background and text for readability
The label accent colors (from your GitHub labels) will still show on card borders
Invalid hex codes will fall back to white background with dark text

Setup & Development

Prerequisites

Node.js 14 or higher
npm

Installation

npm install

Running Locally

Start the local development server:

npm run run

The server will start on port 5002 (or the port specified in the PORT environment variable).

Access your roadmap locally at:

http://localhost:5002/{owner}/{repo}/{bgColor}/{textColor}

Example:

http://localhost:5002/rocketstack-matt/roadmapper/ffffff/24292f

Deployment

This project can be deployed to any serverless platform that supports Node.js:

Fork this repository
Connect to your hosting platform (e.g., Vercel)
Set environment variables:
- GITHUB_TOKEN — GitHub Personal Access Token (recommended, for higher API rate limits)
- UPSTASH_REDIS_REST_URL — Upstash Redis REST URL (required for registration, rate limiting, caching)
- UPSTASH_REDIS_REST_TOKEN — Upstash Redis REST token
- RESEND_API_KEY — Resend API key (optional, enables email confirmation on registration)
- FROM_EMAIL — Sender email address (optional, defaults to Roadmapper <[email protected]>)
Deploy

Without the Upstash Redis variables, the service runs unrestricted (no registration required, no rate limits, no caching). Without RESEND_API_KEY, keys work immediately after registration (no email confirmation required).

How Labels Work

Roadmapper looks for these exact label names on your GitHub issues:

Roadmap: Now - Items appear in the "Now" column
Roadmap: Next - Items appear in the "Next" column
Roadmap: Later - Items appear in the "Later" column

Label Colors

Roadmapper automatically extracts and uses the actual colors from your GitHub labels. Each roadmap card displays a colored accent border at the top that matches the color you've set for that label in your GitHub repository. This means you can customize the appearance of your roadmap by simply changing the label colors in GitHub—no configuration needed!

If a label color cannot be determined, the card will use a default gray color.

Issues are automatically sorted by issue number within each column.

Features

✨ Clean, modern SVG output
🎨 Fully customizable colors (background and text)
🎨 Automatic label color matching from GitHub
🔄 Automatic updates from GitHub issues (free tier refreshes hourly)
📱 Responsive design
🚀 Serverless deployment ready
🔑 Per-repository API keys with rate limiting
⚡ Built-in response caching for fast load times

Rate Limits & Caching

Roadmapper uses per-repository rate limiting and response caching:

Tier	Roadmap Refresh	Rate Limit
Free (registered)	Every 60 minutes	60 requests/hour
Paid (coming soon)	Every 30 seconds	~Unlimited

The cache TTL controls how often your roadmap data refreshes from GitHub. All viewers within the cache window see the same cached response. The rate limit is a secondary protection against abuse.

GitHub API Rate Limits

Roadmapper also uses the GitHub API, which has its own rate limits:

Unauthenticated requests: 60 requests per hour per IP
Authenticated requests: 5,000 requests per hour

Adding GitHub Authentication (Recommended for Production)

To increase the rate limit to 5,000 requests/hour, add a GitHub Personal Access Token:

Create a GitHub Personal Access Token:
- Go to https://github.com/settings/tokens
- Click "Generate new token (classic)"
- Give it a name like "Roadmapper"
- Select scope: public_repo (read access to public repositories)
- Click "Generate token" and copy the token
Add the token to your environment:

For local development:
```
# Create a .env file in the project root
echo "GITHUB_TOKEN=your_token_here" > .env
```
For production (Vercel):
- Go to your Vercel project settings
- Navigate to "Environment Variables"
- Add: GITHUB_TOKEN = your_token_here
Restart the server - The token will be automatically used for all GitHub API requests.

Security Note: Never commit your .env file or expose your token in public repositories.

License

Apache 2.0 - See LICENSE file for details.

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

Name		Name	Last commit message	Last commit date
Latest commit History 47 Commits
api		api
architecture		architecture
lib		lib
public		public
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.roadmapper		.roadmapper
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
roadmap.js		roadmap.js
server.js		server.js
vercel.json		vercel.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Roadmapper

What is Roadmapper?

Live Example

Getting Started

The `.roadmapper` File

How It Works

Usage

URL Format

Examples

In Your README

Custom Colors

Color Examples

Color Tips

Setup & Development

Prerequisites

Installation

Running Locally

Deployment

How Labels Work

Label Colors

Features

Rate Limits & Caching

GitHub API Rate Limits

Adding GitHub Authentication (Recommended for Production)

License

Contributing

About

Uh oh!

Uh oh!

Contributors 3

Uh oh!

Languages

License

rocketstack-matt/roadmapper

Folders and files

Latest commit

History

Repository files navigation

Roadmapper

What is Roadmapper?

Live Example

Getting Started

The .roadmapper File

How It Works

Usage

URL Format

Examples

In Your README

Custom Colors

Color Examples

Color Tips

Setup & Development

Prerequisites

Installation

Running Locally

Deployment

How Labels Work

Label Colors

Features

Rate Limits & Caching

GitHub API Rate Limits

Adding GitHub Authentication (Recommended for Production)

License

Contributing

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Uh oh!

Contributors 3

Uh oh!

Languages

The `.roadmapper` File