https://github.com/ipshipyard/ipfs-quicklaunch
IPFS app launcher browser extension with local pet names, version management, and smart CID discovery
https://github.com/ipshipyard/ipfs-quicklaunch
Last synced: 9 months ago
JSON representation
IPFS app launcher browser extension with local pet names, version management, and smart CID discovery
- Host: GitHub
- URL: https://github.com/ipshipyard/ipfs-quicklaunch
- Owner: ipshipyard
- Created: 2025-07-14T11:02:12.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-11T18:19:11.000Z (9 months ago)
- Last Synced: 2025-08-11T19:32:30.279Z (9 months ago)
- Language: TypeScript
- Homepage:
- Size: 162 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# IPFS QuickLaunch Browser Extension
IPFS QuickLaunch is an experimental browser extension with local nicknames, version management, smart CID discovery, and gateway management.
**Built by [Shipyard](https://ipshipyard.com/) with ❤️ for the IPFS ecosystem**
## ✨ Key Features
- **🏷️ Nickname System**: Save IPFS apps with memorable, user-chosen names
- **📦 Version Management**: Track multiple versions per app with automatic updates
- **🔍 Smart Discovery**: Automatic DNSLink and `x-ipfs-path` header detection
- **🎨 Visual Feedback**: Extension badge notifications and app highlighting
- **🌐 Gateway Flexibility**: Configurable IPFS gateways with local gateway support
- **🌙 Theme System**: Light/Dark/Auto modes with system preference detection
- **💾 Data Management**: Export/import with full backup/restore capabilities
- **⌨️ Keyboard Shortcuts**: Power user navigation (Ctrl+N, Ctrl+F, etc.)
## Disclaimer
This extension is an experimental proof of concept. It's intended to demonstrate UX patterns around local CID management, versioning, and gateway flexibility in the IPFS ecosystem.
## 🚀 Quick Start
To get started with the IPFS QuickLaunch browser extension, you need to build it from source. Follow these steps:
```bash
# Install dependencies
npm install
# Build the extension
npm run build
# Create a .zip for Chrome Web Store
npm run package
```
### Development Commands
```bash
# Run extension in Chrome for development
npm start
# Watch TypeScript files for changes
npm run watch
# Clean build directory
npm run clean
```
### Available npm Scripts
| Command | Description |
|---------|-------------|
| `npm run build` | Compiles TypeScript and copies assets to `dist/` directory |
| `npm run package` | Builds and creates a `.zip` file ready for Chrome Web Store submission |
| `npm start` | Builds and launches the extension in Chrome/Chromium for development |
| `npm run watch` | Watches TypeScript files and recompiles on changes |
| `npm run clean` | Removes the `dist/` build directory |
| `npm run sync-version` | Syncs version from `package.json` to `manifest.json` (runs automatically during build) |
### Installation in Chrome
#### For Development (automatic)
1. Run `npm start` to build and launch the extension in Chrome
2. The extension will be automatically loaded and reloaded when you make changes
3. Chrome will open with the extension pre-installed for testing
#### For Development (manual)
1. Run `npm run build` to compile the extension
2. Open Chrome and navigate to `chrome://extensions`
3. Enable Developer Mode by clicking the toggle switch
4. Click "Load unpacked" and select the `dist/` directory
#### For Chrome Web Store Publishing
1. Run `npm run package` to create `ipfs-quicklaunch-{version}.zip`
2. Upload the generated `.zip` file to [Chrome Web Store Developer Dashboard](https://chrome.google.com/webstore/developer/dashboard)
## 🏗️ Architecture Overview
```
┌─────────────────────────────────────────────────────────────────┐
│ Browser Extension │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Popup UI │ │ Background │ │ Content Script │ │
│ │ │ │ Service Worker │ │ │ │
│ │ • App Management│ │ │ │ • Header Check │ │
│ │ • User Interface│ │ • DNSLink Probe │ │ • Page Context │ │
│ │ • Theme System │ │ • Tab Monitoring│ │ • Same-Origin │ │
│ │ • Form State │ │ • Icon Updates │ │ Requests │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │ │ │ │
│ └─────────────────────┼─────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Chrome Storage API │ │
│ │ • Apps & Versions • Settings & Themes │ │
│ │ • Gateway Config • DNSLink Cache │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ External Services │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ DNS-over- │ │ IPFS Gateways │ │ Local IPFS │ │
│ │ HTTPS │ │ │ │ Gateway │ │
│ │ │ │ • dweb.link │ │ │ │
│ │ • DNSLink TXT │ │ • inbrowser.* │ │ • localhost:8080│ │
│ │ Records │ │ • Custom Gates │ │ • Auto-detect │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## 📁 Project Structure
```
src/
├── manifest.json # Extension manifest (v3)
├── popup.html # Main UI (400px width, responsive)
├── popup.ts # Popup controller & state management
├── background.ts # Service worker & tab monitoring
├── content.ts # Content script for header detection
├── components/
│ ├── AppFlag.ts # Individual app card component
│ └── VersionManager.ts # Version management modal
├── storage/
│ └── index.ts # Storage management & caching
├── types/
│ └── index.ts # TypeScript interfaces
├── utils/
│ ├── theme.ts # Theme system & preferences
│ ├── export.ts # Data backup/restore
│ ├── formState.ts # Form auto-save & persistence
│ ├── dnslink.ts # DNSLink & x-ipfs-path detection
│ ├── localGateway.ts # Local IPFS gateway probing
│ └── ipfs.ts # IPFS utilities & CID validation
└── icons/ # Extension icons (16/48/128px)
```
## 🧠 Core Data Model
```typescript
interface App {
id: string // Unique identifier
nickname: string // User-chosen friendly name
description?: string // Optional description
icon?: string // Optional icon URL
versions: AppVersion[] // Multiple versions per app
tags: string[] // Categorization tags
createdAt: number // Unix timestamp
lastUsed: number // Unix timestamp
}
interface AppVersion {
id: string // Version identifier
name: string // Version name (e.g., "v1.2.0")
cid: string // IPFS CID (primary identifier)
hash?: string // Legacy hash field
isDefault: boolean // Default version flag
createdAt: number // Unix timestamp
}
interface GatewayConfig {
defaultGateway: string // Domain for subdomain resolution
customGateways: string[] // User-defined gateways
preferLocalGateway: boolean // Prefer localhost:8080
localGatewayUrl: string // Local gateway URL
}
interface DNSLinkCacheEntry {
domain: string // Domain name
lastCID: string // Last detected CID
lastChecked: number // Cache timestamp
associatedAppId?: string // Linked app ID
}
```
## 🎯 Key Design Decisions
### 1. **CID-Based Architecture**
- **Decision**: Store IPFS CIDs instead of full URLs
- **Rationale**:
- Gateway-agnostic: Users can switch gateways without losing data
- Future-proof: Works with any IPFS gateway or resolution method
- Efficient: Single CID maps to multiple possible URLs
- **Implementation**: Dynamic URL construction at launch time
### 2. **Dual Detection System**
- **Decision**: Support both DNSLink TXT records and x-ipfs-path headers
- **Rationale**:
- **DNSLink**: Standard IPFS name resolution via DNS
- **x-ipfs-path**: Gateway-served content detection
- **Coverage**: Captures more IPFS content types
- **Implementation**: DNS-over-HTTPS + content script messaging
### 3. **Store-Friendly Permissions**
- **Decision**: Minimal permission set (storage, tabs, activeTab)
- **Rationale**:
- **Fast approval**: Reduced review time for web stores
- **User trust**: Lower permission requests increase adoption
- **Security**: Principle of least privilege
- **Trade-offs**: Limited to DNS-over-HTTPS vs. direct DNS access
### 4. **Local-First Data Management**
- **Decision**: Chrome Storage API with local caching
- **Rationale**:
- **Privacy**: No external servers or analytics
- **Performance**: Local cache for instant access
- **Reliability**: Works offline
- **Backup**: Export/import for data portability
### 5. **Component-Based Architecture**
- **Decision**: Modular TypeScript components
- **Rationale**:
- **Maintainability**: Clear separation of concerns
- **Testability**: Isolated component logic
- **Reusability**: Components used across different contexts
- **Structure**: AppFlag, VersionManager, Storage, Utils
### 6. **Progressive Enhancement**
- **Decision**: Graceful degradation for failed features
- **Rationale**:
- **Reliability**: Core functionality works even if advanced features fail
- **Browser compatibility**: Different environments have different capabilities
- **User experience**: Never block the user due to edge cases
- **Examples**: Content script fallbacks, local gateway detection
### 7. **Modern Subdomain Gateway Support**
- **Decision**: Prefer `https://{cid}.ipfs.{gateway}` over path-based URLs
- **Rationale**:
- **Security**: Proper origin isolation for web apps
- **Performance**: Better caching and CDN support
- **Standards**: Aligns with modern IPFS gateway specifications
- **Fallback**: Support for legacy path-based gateways
### 8. **Real-Time State Management**
- **Decision**: Live tab monitoring and app highlighting
- **Rationale**:
- **Context awareness**: Show which app corresponds to current tab
- **User feedback**: Visual confirmation of saved apps
- **Discovery**: Help users connect URLs to saved apps
- **Implementation**: Background tab monitoring + popup state sync
## 🔧 Development Details
### Build System
- **TypeScript Compilation**: `tsc` with strict type checking
- **Asset Pipeline**: Copy HTML, manifest, and icons to `dist/`
- **Watch Mode**: Automatic rebuilds during development
- **Zero Bundling**: Pure browser APIs, no webpack/rollup complexity
### Performance Optimizations
- **Local Caching**: Storage manager with in-memory cache
- **Debounced Operations**: Form auto-save and search filtering
- **Lazy Loading**: Components instantiated on demand
- **Efficient Queries**: Indexed storage lookups by ID and CID
### Browser Compatibility
- **Manifest V3**: Modern Chrome extension standards
- **ES2020+ Features**: Native modules, async/await, optional chaining
- **Progressive Enhancement**: Core features work across different environments
- **CORS Handling**: DNS-over-HTTPS and content script messaging
### Security Considerations
- **Content Security Policy**: Strict CSP for popup HTML
- **Input Validation**: CID format validation and sanitization
- **Origin Isolation**: Subdomain gateway URLs for proper app separation
- **No External Dependencies**: Self-contained for supply chain security
## 🧪 Testing & Quality
### Type Safety
- **Full TypeScript Coverage**: All source files typed
- **Interface Definitions**: Comprehensive type definitions
- **Strict Compilation**: `noImplicitAny`, `strictNullChecks` enabled
### Error Handling
- **Graceful Degradation**: Fallbacks for all external dependencies
- **User Feedback**: Clear error messages and loading states
- **Debug Logging**: Console logging for development and debugging
- **Exception Safety**: Try-catch blocks around critical operations
## 📦 Distribution
### Chrome Web Store Ready
- **Minimal Permissions**: Only `storage`, `tabs`, `activeTab`
- **Privacy Compliant**: No external analytics or tracking
- **Content Security Policy**: Strict CSP without `unsafe-eval`
- **Manifest V3**: Future-proof extension format
### Development Workflow
```bash
# Install dependencies
npm install
# Development - launches in Chrome with auto-reload
npm start
# Or watch TypeScript files for manual reload
npm run watch
# Production build for testing
npm run build
# Create .zip for Chrome Web Store
npm run package
# Load dist/ folder in Chrome Developer Mode
chrome://extensions/ -> "Load unpacked"
```
## 🤝 Contributing
### Code Style
- **TypeScript**: Strict typing with interfaces
- **Modern ES6+**: Arrow functions, destructuring, async/await
- **Component Pattern**: Self-contained, reusable components
- **Error-First**: Explicit error handling and user feedback
### Architecture Principles
1. **Separation of Concerns**: Clear boundaries between UI, storage, and utilities
2. **Progressive Enhancement**: Core functionality always available
3. **User Privacy**: Local-first data management
4. **Performance**: Efficient caching and minimal network requests
5. **Accessibility**: Keyboard navigation and screen reader support
---
**Built by [Shipyard](https://ipshipyard.com/) with ❤️ for the IPFS ecosystem**