Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/bitkarrot/thelookup

A self curating nostr directory with nip-57 payments
https://github.com/bitkarrot/thelookup

Last synced: 3 months ago
JSON representation

A self curating nostr directory with nip-57 payments

Awesome Lists containing this project

README 

          
# 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/](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](https://github.com/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:



```bash

# 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:



```bash

# .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):**

```bash

# Don't set VITE_SITE_NAME or leave it empty

# VITE_SITE_NAME=

```



**Curated directory (shows only tagged listings):**

```bash

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):**

```bash

# Don't set VITE_SECTIONS or leave it empty

# VITE_SECTIONS=

```



**Show only specific sections:**

```bash

VITE_SECTIONS=listings,apps

# Only shows listings and apps in navigation and profile pages

```



**Business-focused directory:**

```bash

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



```bash

# 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:



```bash

# .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](https://tweakcn.com). To add a new theme:



```bash

# 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](./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](./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](./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

```json

{

  "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