Radar - Open Source Directory Platform

Build beautiful, Git-powered directories for projects, startups, tools, or any curated collection

Radar is a modern, production-ready platform for creating and managing curated directories of projects, websites, startups, or any collection you want to showcase. Built with Next.js 16, it offers a complete solution with search, filtering, auto-validation, GitHub integration, and beautiful UI out of the box.

Live Reference: fossradar.dev - India's open source project directory powered by Radar

🎯 Use Cases

What can you build with Radar?

🚀 Startup Directories - Showcase startups, SaaS products, or indie projects
🛠️ Tool Catalogs - Curate developer tools, AI apps, or productivity software
📦 Open Source Projects - Directory of libraries, frameworks, or packages
🌍 Regional Showcases - Projects from specific countries, cities, or communities
🏢 Company Portfolios - Internal tool catalogs or client project showcases
🎓 Educational Resources - Course directories, learning platforms, or tutorials
🎨 Creative Works - Portfolio sites, design systems, or template libraries

Examples of directories you can build:

"Awesome Developer Tools from Europe"
"YC-Funded Startups Directory"
"Open Source AI Projects"
"Indie Maker Showcase"
"Government Tech Projects"

✨ Why Radar?

Complete Directory Solution Out of the Box

No database setup, no complex backends - just Git, TOML files, and modern web tech.

For Directory Visitors

🔍 Smart Fuzzy Search - Search across names, descriptions, and tags
🏷️ Multi-Category Filtering - Filter by technology, tags, or custom fields
🗺️ Geographic Visualization - Interactive maps showing location-based distribution
📱 Responsive Design - Perfect on mobile, tablet, and desktop
🌙 Dark Mode - System-aware, beautiful dark theme
🎨 Dynamic Social Cards - Auto-generated OpenGraph images (1200×630)
🔄 Social Sharing - Share on Twitter, LinkedIn, Facebook, email

For Content Submitters

🚀 No-Code Submission Form - 5-step guided form with auto-fill
🤖 Auto PR Creation - GitHub OAuth to create pull requests automatically
✅ Real-Time Validation - Helpful error messages as you type
🔍 Duplicate Detection - Prevents resubmissions
🏷️ Smart Suggestions - Auto-suggests tags from GitHub topics
🖼️ Logo Upload - Drag-and-drop file upload in the form
📝 TOML Preview - See exactly what will be created

For Directory Maintainers

Git as Database - All data version-controlled in TOML files
Auto-Validation CI - Every submission automatically validated
Auto-Enrichment - Nightly updates for stars, contributors, metadata
GitHub Integration - OAuth, API, webhooks built-in
SEO Optimized - Sitemaps, structured data, meta tags
Zero Runtime DB - Fast, simple, auditable
One-Click Deploy - Deploy to Vercel in minutes

🚀 Quick Start

Deploy Your Own Directory in 5 Minutes

1. Fork this repository

Click the "Fork" button at the top of this page

2. Deploy to Vercel

Or manually:

Go to vercel.com/new
Import your forked repository
Vercel will auto-detect Next.js and configure everything

3. Configure Environment Variables (Optional for enhanced features)

Add these in Vercel dashboard → Settings → Environment Variables:

# GitHub OAuth (required for submission form & star button)
GITHUB_CLIENT_ID=your_github_oauth_client_id
GITHUB_CLIENT_SECRET=your_github_oauth_client_secret

# NextAuth (required for authentication)
NEXTAUTH_SECRET=your_random_secret_here  # Generate: openssl rand -base64 32
NEXTAUTH_URL=https://yourdomain.com

# GitHub Token (automatically provided in CI - no setup needed!)
# Only needed for local testing of validation/enrichment
GITHUB_TOKEN=ghp_your_token_here

4. Customize Your Directory

Edit configuration files to match your use case:

data/projects/ - Add your initial entries (TOML files)
data/tags.toml - Define allowed categories/tags
app/layout.tsx - Update site name, description, metadata
public/logos/ - Add project/company logos
Customize colors, fonts, and styling in tailwind.config.ts

5. Push & Deploy

git add .
git commit -m "Customize directory"
git push origin main

Vercel will auto-deploy your changes!

🏗️ Local Development

Prerequisites

Node.js 18+ (20+ recommended)
pnpm (or npm/yarn)

Setup

# Clone your forked repository
git clone https://github.com/YOUR_USERNAME/radar.git
cd radar

# Install dependencies
pnpm install

# Copy environment template (optional for local dev)
cp .env.example .env

# Run development server
pnpm dev

Visit http://localhost:3000

Note: GitHub token is NOT required for UI development. Only needed if you want to test validation/enrichment scripts locally.

Available Commands

# Development
pnpm dev              # Start dev server
pnpm build            # Build for production
pnpm start            # Start production server

# Data Management
pnpm validate         # Validate all TOML files
pnpm run build:index  # Generate search index
pnpm enrich           # Update metadata (requires GITHUB_TOKEN)

# Code Quality
pnpm lint             # Run ESLint

📝 Adding Entries to Your Directory

Method 1: Submission Form (Recommended)

Visit /submit/form on your deployed site for a guided submission experience.

Features:

Auto-fetch project details from GitHub
Real-time validation
Drag-and-drop logo upload
TOML preview
Automatic PR creation (requires GitHub OAuth)

Method 2: Manual Git Workflow

Step 1: Create TOML file

Create data/projects/your-entry-slug.toml:

slug = "your-project"
name = "Your Awesome Project"
short_desc = "Brief description (10-160 characters)"
repo = "https://github.com/username/project"
license = "MIT"
added_at = "2025-11-12"

website = "https://yourproject.com"
logo = "/logos/your-project.svg"
primary_lang = "TypeScript"
category = "web-applications"  # Required: Choose from data/categories.json
tags = ["web", "tools", "typescript"]
looking_for_contributors = true

# Customize these fields for your use case
location_city = "San Francisco"
location_indian_state = "California"  # Rename this field as needed

Step 2: Add logo (optional)

Place logo file (SVG/PNG, max 200KB) in public/logos/

Step 3: Commit and create PR

git add data/projects/your-entry.toml public/logos/your-logo.svg
git commit -m "Add Your Project"
git push origin main

🎨 Customization Guide

Branding & Metadata

Site Information (app/layout.tsx)

export const metadata: Metadata = {
  title: "Your Directory Name",
  description: "Your directory description",
  // Update OpenGraph, Twitter cards, etc.
}

Visual Identity (tailwind.config.ts)

Update colors, fonts, spacing
Customize theme (light/dark modes)

Data Schema

Categories (data/categories.json) - Main classification

{
  "categories": {
    "web-applications": {
      "label": "Web Applications",
      "description": "Full-stack web apps, SaaS platforms",
      "icon": "globe"
    }
  }
}

Each entry must select exactly one category. Customize for your directory theme:

Open Source Projects: developer-tools, libraries-frameworks, ai-ml, etc.
Privacy Tools: security-privacy, networking (VPN), system-utilities
Startup Directory: web-applications, mobile-applications, automation-productivity
Dev Tools Catalog: developer-tools, infrastructure-devops, content-media

Tags (data/tags.toml) - Secondary attributes

tags = ["web", "nextjs", "typescript", "cms"]

Tags provide fine-grained filtering within categories (1-10 tags per entry).

Entry Schema (lib/schema.ts)

Customize required/optional fields
Add custom validation rules
Modify data structure

Features Toggle

Enable/Disable Features:

Geographic radar (app/radar/)
GitHub OAuth (lib/auth.ts)
Auto-enrichment (.github/workflows/enrich.yml)
Submission form (app/submit/form/)

🏗️ Architecture

Tech Stack

Framework: Next.js 16 (App Router, React 19, TypeScript 5.6)
Styling: Tailwind CSS 4 (latest major version)
Fonts: VT323 (logo), Share Tech (headings), Inter (body)
Search: Fuse.js (client-side fuzzy search)
Validation: Zod schemas
Icons: Lucide React
Deployment: Vercel (recommended) or any Node.js host
Data: TOML files in Git (no database!)

Project Structure

radar/
├── app/                        # Next.js pages and routes
│   ├── page.tsx               # Homepage with search/filter
│   ├── about/                 # About page
│   ├── radar/                 # Geographic visualization
│   ├── projects/[slug]/       # Individual project pages
│   ├── submit/form/           # Submission form
│   └── api/                   # API routes
├── components/                # React components
├── data/
│   ├── projects/              # Project TOML files
│   ├── tags.toml              # Allowed tags
│   └── licenses-osi.json      # OSI licenses
├── lib/                       # Utilities and helpers
├── scripts/                   # Build and validation
└── public/

Fossradar

Install / Use

README