Skip to content

Pubky Explorer

Pubky Explorer is a web-based file browser for exploring public data stored on Pubky Homeservers. It provides an intuitive interface for navigating the decentralized file system, previewing files, and sharing direct links to specific content—all without requiring authentication or installation.

Live Application: https://explorer.pubky.app

Overview

Section titled “Overview”

Pubky Explorer makes it easy to browse the public data stored across the Pubky network. Unlike traditional file explorers that require local access, Pubky Explorer operates entirely in the browser, fetching data directly from Homeservers using the Pubky SDK.

Key Features

Section titled “Key Features”
  • Zero Installation: Runs entirely in the browser, no downloads required
  • Public-Key Navigation: Enter any 52-character public key to browse their data
  • Directory Traversal: Navigate through nested directories like a traditional file browser
  • File Preview: View file contents directly in the browser (text, JSON, images)
  • Keyboard Navigation: Full keyboard shortcuts for efficient browsing
  • Shareable URLs: Generate permanent links to specific files or directories
  • Sorting Options: Alphabetical sorting (A-Z, Z-A) with directories-first option
  • Shallow Mode: Limit directory depth for faster browsing
  • Responsive Design: Works on desktop and mobile browsers

How It Works

Section titled “How It Works”

Pubky Explorer uses the Pubky SDK to:

  1. Resolve Public Keys: Convert public keys to Homeserver URLs via PKARR
  2. List Directories: Fetch directory contents from Homeservers
  3. Fetch Files: Retrieve individual files for preview
  4. Display Content: Render files appropriately based on content type

All operations happen client-side in your browser—no data is sent to intermediary servers.

Usage

Section titled “Usage”

Basic Navigation

Section titled “Basic Navigation”

Enter a Public Key:

7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy

With Path:

7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy/pub/pubky.app/

With URI Prefix:

pubky://7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy/
pk:7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy/

URL Formats

Section titled “URL Formats”

Pubky Explorer supports multiple URL formats for sharing:

Query Parameter:

https://explorer.pubky.app?p=<public-key>/<path>

Hash Fragment:

https://explorer.pubky.app#p=<public-key>/<path>

Both formats work identically—choose based on your preference for analytics or browser compatibility.

Keyboard Shortcuts

Section titled “Keyboard Shortcuts”

Efficient navigation without touching the mouse:

  • ↑ / ↓: Navigate up/down through files and directories
  • Enter: Open selected file/directory
  • Backspace: Go to parent directory
  • ← / →: Browser back/forward navigation
  • /: Focus search input

File Actions

Section titled “File Actions”

Directory Actions:

  • Click directory name to enter it
  • Hover to prefetch contents for instant loading
  • Click breadcrumb path to jump to parent directories

File Actions:

  • Click file name to preview contents
  • Preview opens in side panel
  • Close preview to return to directory listing

Viewing Options

Section titled “Viewing Options”

Shallow Mode:

  • Checkbox option to limit recursion depth
  • Faster loading for large directory structures
  • Useful for quick exploration

Sorting:

  • A-Z: Alphabetical ascending
  • Z-A: Alphabetical descending
  • Dirs First: Group directories before files

Sharing

Section titled “Sharing”

Share Button:

  • Generates shareable URL for current view
  • Copies to clipboard automatically
  • Includes exact path and file state
  • Recipients see identical view

Use Cases

Section titled “Use Cases”

Data Verification

Section titled “Data Verification”

Verify published data structure:

  • Check if profile exists at expected path
  • Inspect post formatting and metadata
  • Validate pubky-app-specs compliance

Debugging

Section titled “Debugging”

Debug application issues:

  • Inspect actual stored data format
  • Compare expected vs. actual file structure
  • Verify permission issues aren’t data-related

Discovery

Section titled “Discovery”

Explore the Pubky network:

  • Browse public user data
  • See how applications structure data
  • Learn common path conventions

Documentation

Section titled “Documentation”

Create documentation with real examples:

  • Share links to actual data structures
  • Reference real posts/profiles in tutorials
  • Provide working examples for developers

Research

Section titled “Research”

Study the Pubky ecosystem:

  • Analyze data usage patterns
  • Survey application conventions
  • Gather statistics on data types

Technical Details

Section titled “Technical Details”

Technology Stack

Section titled “Technology Stack”
  • Frontend Framework: SolidJS (reactive UI)
  • Build Tool: Vite (fast development and bundling)
  • Language: TypeScript (type-safe development)
  • Pubky Integration: @synonymdev/pubky SDK
  • Styling: CSS with modern features

Architecture

Section titled “Architecture”

Client-Side Only:

  • No backend server required
  • All data fetched directly from Homeservers
  • Privacy-preserving (no tracking)
  • Censorship-resistant (no proxy)

State Management:

  • Reactive state using SolidJS signals
  • Directory listing cache for performance
  • Scroll position preservation
  • Browser history integration

Performance Optimizations:

  • Directory prefetching on hover/focus
  • Lazy loading for large directories
  • Intersection observer for infinite scroll
  • Efficient re-rendering with fine-grained reactivity

Data Flow

Section titled “Data Flow”
User Input → SDK Resolution → Homeserver Request → Data Display
    ↓              ↓                    ↓                ↓
Public Key    PKARR Lookup      HTTP/HTTPS        Render List
  or Path       (via DHT)        (via SDK)       or Preview

Supported File Types

Section titled “Supported File Types”

Preview Support:

  • Text: .txt, .md, .log
  • Code: .js, .ts, .json, .html, .css
  • Data: .json, .yaml, .xml
  • Images: .jpg, .png, .gif, .svg, .webp
  • Documents: Raw text rendering for inspection

Download Fallback:

  • Binary files prompt download
  • Large files may timeout (browser limits)
  • Unknown types rendered as text when possible

Development

Section titled “Development”

Local Setup

Section titled “Local Setup”
Terminal window
# Clone repository
git clone https://github.com/pubky/pubky-explorer
cd pubky-explorer


# Install dependencies
npm install


# Start development server
npm run dev


# Open browser to http://localhost:5173

Building for Production

Section titled “Building for Production”
Terminal window
# Build optimized bundle
npm run build


# Preview production build
npm run preview

Output in dist/ directory ready for static hosting.

Project Structure

Section titled “Project Structure”
pubky-explorer/
├── src/
│   ├── App.tsx           # Main application component
│   ├── Explorer.tsx      # Directory browser UI
│   ├── Preview.tsx       # File preview panel
│   ├── ShareButton.tsx   # Share URL generator
│   ├── Spinner.tsx       # Loading indicator
│   ├── state.ts          # Global state management
│   └── css/              # Component styles
├── public/
│   └── pubky.svg         # Logo asset
├── index.html            # HTML entry point
├── vite.config.ts        # Vite configuration
└── package.json          # Dependencies

Configuration

Section titled “Configuration”

Environment Variables:

None required! Pubky Explorer works entirely with the public Pubky SDK and requires no API keys or configuration.

Deployment:

Deploy to any static hosting service:

  • Vercel: vercel deploy
  • Netlify: Drag & drop dist/ folder
  • GitHub Pages: Push dist/ to gh-pages branch
  • Cloudflare Pages: Connect repository
  • AWS S3: Upload dist/ contents

Privacy & Security

Section titled “Privacy & Security”

Privacy Features

Section titled “Privacy Features”
  • No Analytics: Zero tracking by default
  • No Cookies: Stateless operation
  • No Server: Direct Homeserver connections
  • Client-Side: All computation in browser
  • No Data Collection: Nothing stored externally

Security Considerations

Section titled “Security Considerations”
  • Public Data Only: Only displays public Homeserver data
  • No Authentication: Cannot access private data
  • Read-Only: Cannot modify or upload data
  • CORS Limitations: Subject to Homeserver CORS policies
  • Browser Sandbox: Runs in browser security context

Data Visibility

Section titled “Data Visibility”

What Explorer Can See:

  • Public directories on Homeservers
  • Files with read permissions
  • Metadata (file sizes, structure)

What Explorer Cannot See:

  • Private or encrypted data
  • Authentication-required content
  • Data without proper CORS headers

Limitations

Section titled “Limitations”

Technical Constraints

Section titled “Technical Constraints”
  • Large Files: Browser memory limits may cause issues
  • Many Files: Extremely large directories may be slow
  • Binary Files: Limited preview support for binary formats
  • Recursive Depth: Deep nesting may impact performance
  • Network Speed: Limited by Homeserver response times

Functional Limitations

Section titled “Functional Limitations”
  • Read-Only: No upload or edit capabilities
  • No Authentication: Cannot access private data
  • Public Data: Only works with publicly readable content
  • CORS Dependent: Requires Homeserver CORS support
  • Single Homeserver: No multi-homeserver aggregation

Future Enhancements

Section titled “Future Enhancements”

Potential improvements for Pubky Explorer:

  • File Upload: Enable data publishing (with authentication)
  • Editing: In-browser file editing with SDK write operations
  • Search: Full-text search across user’s data
  • History: Recent locations and favorites
  • Bulk Operations: Select multiple files for actions
  • Advanced Preview: Markdown rendering, syntax highlighting
  • Data Visualization: Charts for JSON data, image galleries
  • Comparison View: Diff between file versions
  • Mobile App: Native iOS/Android applications
  • Offline Support: Service worker for caching
Section titled “Related Tools”
  • Pubky SDK: Underlying data access library
  • PKDNS: DNS resolution for public keys (used by SDK)
  • Pubky App: Social application using same data structures
  • pubky-app-specs: Data model specifications
  • Pubky Nexus: Backend for aggregated views (Explorer shows raw data)

Resources

Section titled “Resources”

See Also

Section titled “See Also”