TheLookup

A comprehensive Nostr ecosystem explorer and directory for discovering NIPs, applications, repositories, and resources in the decentralized social network.

Important Note: The Lookup is a Nostr client that supports flexible directory configurations. You can create either an open directory (showing all content from your relay) or a curated directory (showing only content tagged with your client tag). For curated directories, it's best used with a relay that automatically removes notes flagged by kind 1984 by relay moderators. Alternatively use an instance from relay.tools or nostr.land where you can customize the settings in a point-and-click interface.

🌐 Live Site: https://nostrlookup.vercel.app/

Features

📱 Application Directory

• Discover Nostr Apps: Browse a comprehensive directory of Nostr applications
• Detailed App Profiles: View screenshots, descriptions, features, and metadata
• Category Filtering: Filter apps by type, platform, and functionality
• Community Submissions: Submit and edit your own applications
• Community Moderation: Report and flag inappropriate content using NIP-1984

🏬 Business Listings Directory

• NIP-15 Business Stalls: Discover marketplace stalls and businesses published on Nostr
• Client Tag Filtering: Configurable filtering to show all listings or only those tagged with your client
• Search & Filter: Search listings by name and description, and filter by tags
• Rich Listing Details: Dedicated detail pages with images, description, Nostr event data, and shipping zones
• Owner Controls: Listing owners can edit their stalls and request deletion via NIP-09
• Listing Flagging: Community members can flag listings with NIP-1984 reports (fraud, spam, scam, duplicate, inappropriate, impersonation)
• Profile Integration: Each listing displays the author's profile name with direct links to their Nostr profile
• Author Pages: View all listings created by a specific author on their profile page

📖 NIPs (Nostr Implementation Possibilities)

• Official NIPs: Browse and search through official NIPs from the nostr-protocol/nips repository
• Custom NIPs: Publish your own custom NIPs on the Nostr network using kind 30817 events
• Rich Markdown: Full markdown rendering with syntax highlighting for code blocks
• NIP-19 Support: Support for naddr identifiers and direct linking
• Edit & Update: Edit and update your published NIPs

🗂️ Repository Explorer

• Git Repository Discovery: Browse Nostr-related repositories and projects
• Issue Tracking: View and create issues for repositories
• Patch Management: Submit and review patches
• Repository Announcements: Announce new repositories to the community

🌐 Resources Hub

• Essential Tools: Curated list of Nostr tools, services, and gateways
• Community Resources: Discover relays, clients, and development resources
• Categorized Listings: Organized by type (Official, Relay, Tools, Gateway, etc.)

🔧 Developer Tools

• DVM Marketplace: Discover and interact with Data Vending Machines
• Event Explorer: View and analyze Nostr events by kind
• Author Profiles: Explore user profiles and their contributions across all sections

👤 Enhanced Profile Pages

• Section Configuration: Configurable sections based on VITE_SECTIONS environment variable
• Author Listings: Display business listings created by profile owners
• Profile Links: Direct links to author profiles from listing and app cards
• Comprehensive Views: Shows Custom NIPs, Apps, Repositories, and Listings based on configuration
• Owner Controls: Edit and delete actions for profile owners on their own content

🎨 Modern UI/UX

• Beautiful Themes: Support for tweakcn.com themes with OKLCH color spaces
• Responsive Design: Works seamlessly on desktop and mobile devices
• Dark/Light Mode: Automatic theme switching with system preference detection
• Smooth Animations: Polished interactions and transitions
• Optimized Images: Circular avatars with proper cropping using object-fit for professional appearance
• Profile Integration: Seamless profile links throughout listings and app cards

URL Structure

Main Sections

• / - Business listings directory (home page)
• /resources - Nostr resources and tools hub
• /nips - NIPs browser and directory
• /repositories - Git repository explorer
• /dvm - Data Vending Machine marketplace

Business Listings

• /listings - Business directory for NIP-15 marketplace stalls
• /listings/submit - Submit a new business listing
• /listings/:stallId - View business listing details
• /listings/:stallId/edit - Edit an existing business listing (owner only)

NIPs

• /nip/01 - View official NIP-01
• /nip/naddr1... - View custom NIP by naddr (NIP-19 identifier)
• /create - Create a new custom NIP
• /edit/naddr1... - Edit an existing custom NIP (owner only)

Applications

• /apps - Browse all applications
• /apps/t/:tag - Filter apps by category tag
• /apps/submit - Submit a new application
• /apps/edit/:naddr - Edit an existing application

Repositories

• /repositories - Browse all repositories
• /repositories/create - Announce a new repository
• /repositories/:naddr - View repository details
• /repositories/:naddr/edit - Edit repository information
• /repositories/:naddr/issues/create - Create new issue
• /repositories/:nip19/issues/:issueId - View specific issue
• /repositories/:nip19/patches/:patchId - View specific patch

Other

• /kind/:k - View events by Nostr event kind
• /:nip19 - Universal NIP-19 identifier resolver
• /notifications - User notifications

Custom NIP Format

Custom NIPs are published as kind 30817 events with the following structure:

• content: The markdown content of the NIP
• d tag: Unique identifier for the NIP
• title tag: The title of the NIP
• k tags: Event kinds that this NIP defines or relates to (optional)

Technology Stack

Frontend

• React 18 with TypeScript for robust component architecture
• Vite for fast development and optimized builds
• React Router for client-side routing
• TanStack Query for efficient data fetching and caching

Styling & UI

• TailwindCSS for utility-first styling
• shadcn/ui for beautiful, accessible UI components
• tweakcn.com themes for customizable color schemes with OKLCH support
• Lucide React for consistent iconography
• Radix UI for headless, accessible component primitives

Nostr Integration

• Nostrify for Nostr protocol integration and event handling
• nostr-tools for additional Nostr utilities
• NIP-07 browser extension support for authentication

Content & Media

• React Markdown with remark-gfm for GitHub Flavored Markdown
• Prism.js for syntax highlighting in code blocks
• QR Code generation for sharing
• Rehype Highlight for enhanced code highlighting

Development & Testing

• ESLint with TypeScript support for code quality
• Vitest for unit testing
• Testing Library for component testing
• SWC for fast compilation

Environment Variables

The site can be customized by setting environment variables. Copy .env.example to .env and customize:

# Site Configuration
VITE_SITE_NAME=lookup-client           # Client tag for filtering listings (optional)
VITE_SITE_URL=https://thelookup.app    # Full site URL
VITE_SITE_DISPLAY_NAME=TheLookup       # Display name shown in UI

# Navigation Configuration
VITE_SECTIONS=listings,apps,nips       # Comma-separated list of visible sections (optional)

Deployment Customization

When deploying your own instance, you can customize:

1. Site Name: Changes the client tag in published events and redirect targets
2. Site URL: Used for any absolute URLs that reference the site
3. Display Name: The name shown in the UI and page titles

Example for a custom deployment:

# .env
VITE_SITE_NAME=my-nostr-directory.com
VITE_SITE_URL=https://my-nostr-directory.com
VITE_SITE_DISPLAY_NAME=My Nostr Directory

Client Tag Filtering

The business listings directory supports client tag filtering to create curated directories:

How It Works

• No VITE_SITE_NAME set: Shows all business listings from the relay
• VITE_SITE_NAME configured: Shows only listings tagged with that client tag

Use Cases

1. Open Directory: Don't set VITE_SITE_NAME to show all businesses on your relay
2. Curated Directory: Set VITE_SITE_NAME=my-client to show only businesses tagged with "my-client"
3. Multi-Client Relay: Different instances can show different subsets of the same relay's data

Configuration Examples

Open directory (shows all listings):

# Don't set VITE_SITE_NAME or leave it empty
# VITE_SITE_NAME=

Curated directory (shows only tagged listings):

VITE_SITE_NAME=my-business-directory
# Only shows listings tagged with "my-business-directory"

Technical Details

• Client tags are added automatically to events published by your instance
• Filtering happens at the data layer for optimal performance
• Other instances can use the same relay with different client tags
• Backward compatible with existing deployments

Section Configuration

Control which sections appear in the navigation and profile pages using the VITE_SECTIONS environment variable:

Available Sections

• resources - Nostr resources and tools hub
• nips - NIPs browser and custom NIPs
• apps - Application directory
• listings - Business listings directory
• repositories - Git repository explorer
• dvm - Data Vending Machine marketplace

Configuration Examples

Show all sections (default):

# Don't set VITE_SECTIONS or leave it empty
# VITE_SECTIONS=

Show only specific sections:

VITE_SECTIONS=listings,apps
# Only shows listings and apps in navigation and profile pages

Business-focused directory:

VITE_SECTIONS=listings,resources
# Perfect for business directories with supporting resources

Profile Page Integration

• Profile pages automatically respect the section configuration
• Only configured sections will display author content
• Maintains consistent user experience across navigation and profiles
• Authors can only see edit/delete controls for visible sections

Development

# Install dependencies and start development server
npm run dev

# Run tests
npm run test

# Build for production
npm run build

# Deploy
npm run deploy

Development Environment Variables

For development, you can create .env.local to override settings locally without affecting the repository:

# .env.local (for development only)
VITE_SITE_NAME=localhost:5173
VITE_SITE_URL=http://localhost:5173
VITE_SITE_DISPLAY_NAME=TheLookup

Theme Customization

TheLookup supports beautiful themes from tweakcn.com. To add a new theme:

# Find a theme on tweakcn.com and use the CLI
npx shadcn@latest add https://tweakcn.com/r/themes/[theme-id]

The theme system uses OKLCH color spaces for vibrant, consistent colors across light and dark modes.

Lightning Payments

TheLookup supports Lightning payments for submissions (apps and business listings) to prevent spam and maintain directory quality:

• NIP-57 Integration: Uses Lightning Zaps for payment verification
• Configurable Fees: Set custom satoshi amounts for new submissions
• Smart Logic: Only new users pay - existing authors/listing owners can edit for free
• Multiple Wallets: Supports QR codes, WebLN, and manual invoice copying
• Anti-Spam: Helps maintain high-quality directories

Key environment variables:

• Apps: VITE_SUBMIT_APP_PAYMENT_ENABLED, VITE_SUBMIT_APP_LIGHTNING_ADDRESS, VITE_SUBMIT_APP_FEE
• Business listings: VITE_SUBMIT_LISTING_PAYMENT_ENABLED, VITE_SUBMIT_LISTING_LIGHTNING_ADDRESS, VITE_SUBMIT_LISTING_FEE

For detailed setup instructions, configuration options, and troubleshooting, see LIGHTNING_PAYMENTS.md.

Resources Management

The /resources page displays community resources from a markdown file for easy editing:

• Non-Technical Editing: Resources are stored in public/RESOURCES.md
• Simple Format: Each resource uses standard markdown with metadata
• No Code Required: Add, edit, or remove resources without touching code
• Automatic Icons: Choose from predefined Lucide icons
• Categories: Organize resources by type (Official, Relay, Tools, etc.)

To edit resources, simply modify public/RESOURCES.md following the documented format.

Featured Apps Management

The /apps page displays featured Nostr applications in an auto-rotating carousel from a markdown file for easy curation:

• Auto-Rotating Carousel: 4-second intervals with smooth transitions and infinite loop
• Responsive Layout: Shows 2-4 cards per row based on screen width (mobile: 2, tablet: 3, desktop: 4)
• Authentic Icons: Uses actual website favicons/logos via remote URLs
• Community Curation: Featured apps are stored in public/FEATURED_APPS.md
• Rich Metadata: Each app includes category, platform, description, and icon URL
• Platform Support: Tag apps by platform (Web, iOS, Android, Desktop, All)
• Categories: Organize by type (Social, Client, Tools, Media, Gaming, etc.)
• Interactive Features: Manual navigation, hover effects, and click-to-visit functionality
• Strategic Placement: Positioned prominently at the top of /apps page above search filters

Icon Support:

• Remote URLs: Use https://website.com/favicon.ico for actual website icons
• Fallback Icons: Lucide icon names for consistent styling when needed

To manage featured apps, edit public/FEATURED_APPS.md following the documented format.

Content Flagging System

The app and business listing directories include a community-driven content moderation system using NIP-1984 report events:

Report Categories

• fraud - Fake information
• spam - Unwanted promotional content
• scam - Malicious/deceptive content
• duplicate - Duplicate entries
• inappropriate - Violates community standards
• impersonation - Fake identity/business

How Flagging Works

1. Signed-in users can flag any app from the app detail page
2. Flag reports are published as kind 1984 events on Nostr
3. Flag counts are displayed prominently on app detail pages
4. Severity indicators show warning levels based on flag count
5. One flag per user prevents duplicate reports from the same person

Flag Event Structure

{
  "kind": 1984,
  "pubkey": "flagger_pubkey",
  "content": "This directory entry appears to be fraudulent - fake business information",
  "tags": [
    ["e", "target_event_id", "relay_url"],
    ["p", "target_author_pubkey"],
    ["report", "fraud"],
    ["l", "app-flag", "thelookup.app.flags"],
    ["k", "31990"]
  ]
}

Community Guidelines

• Only flag apps that violate community standards
• Provide detailed descriptions for your reports
• False reports may result in account suspension
• Flag data is public and visible to all users

Contributing

TheLookup welcomes contributions from the Nostr community! Here's how you can help:

Code Contributions

• Report bugs or suggest features via GitHub issues
• Submit pull requests for improvements and new features
• Improve documentation and help others understand the codebase
• Add tests to ensure reliability and prevent regressions

Content Contributions

• Submit applications to the directory
• Create and share your own custom NIPs
• Announce repositories and projects
• Curate resources and help maintain quality listings

Community Contributions

• Test new features and provide feedback
• Help moderate content through the flagging system
• Share TheLookup with other Nostr users and developers
• Translate the interface to other languages (future feature)

Development Setup

1. Fork the repository on GitHub
2. Clone your fork locally
3. Install dependencies: npm install
4. Start development server: npm run dev
5. Make your changes and test thoroughly
6. Submit a pull request with a clear description

License

MIT License - see LICENSE file for details.

---

Built with ❤️ for the Nostr community

TheLookup is an open-source project dedicated to making the Nostr ecosystem more discoverable and accessible to everyone.

The Lookup is based on a fork of nostrhub.io