{"id":30207131,"url":"https://github.com/ipshipyard/ipfs-quicklaunch","last_synced_at":"2025-08-13T16:04:24.328Z","repository":{"id":306213100,"uuid":"1019458820","full_name":"ipshipyard/ipfs-quicklaunch","owner":"ipshipyard","description":"IPFS app launcher browser extension with local pet names, version management, and smart CID discovery","archived":false,"fork":false,"pushed_at":"2025-08-11T18:19:11.000Z","size":166,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-11T19:32:30.279Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ipshipyard.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-14T11:02:12.000Z","updated_at":"2025-08-11T18:19:14.000Z","dependencies_parsed_at":"2025-07-24T11:29:05.741Z","dependency_job_id":"4e96a8d0-63f3-4710-b26a-c04f96ce554c","html_url":"https://github.com/ipshipyard/ipfs-quicklaunch","commit_stats":null,"previous_names":["ipshipyard/ipfs-quicklaunch"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/ipshipyard/ipfs-quicklaunch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipshipyard%2Fipfs-quicklaunch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipshipyard%2Fipfs-quicklaunch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipshipyard%2Fipfs-quicklaunch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipshipyard%2Fipfs-quicklaunch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipshipyard","download_url":"https://codeload.github.com/ipshipyard/ipfs-quicklaunch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipshipyard%2Fipfs-quicklaunch/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270183592,"owners_count":24541338,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-13T02:00:09.904Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-13T16:01:50.369Z","updated_at":"2025-08-13T16:04:24.281Z","avatar_url":"https://github.com/ipshipyard.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IPFS QuickLaunch Browser Extension\n\nIPFS QuickLaunch is an experimental browser extension with local nicknames, version management, smart CID discovery, and gateway management.\n\n**Built by [Shipyard](https://ipshipyard.com/) with ❤️ for the IPFS ecosystem**\n\n![Shipyard](https://github.com/user-attachments/assets/39ed3504-bb71-47f6-9bf8-cb9a1698f272)\n\n\n## ✨ Key Features\n\n- **🏷️ Nickname System**: Save IPFS apps with memorable, user-chosen names\n- **📦 Version Management**: Track multiple versions per app with automatic updates\n- **🔍 Smart Discovery**: Automatic DNSLink and `x-ipfs-path` header detection\n- **🎨 Visual Feedback**: Extension badge notifications and app highlighting\n- **🌐 Gateway Flexibility**: Configurable IPFS gateways with local gateway support\n- **🌙 Theme System**: Light/Dark/Auto modes with system preference detection\n- **💾 Data Management**: Export/import with full backup/restore capabilities\n- **⌨️ Keyboard Shortcuts**: Power user navigation (Ctrl+N, Ctrl+F, etc.)\n\n## Disclaimer\n\nThis 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.\n\n\n## 🚀 Quick Start\n\nTo get started with the IPFS QuickLaunch browser extension, you need to build it from source. Follow these steps:\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the extension\nnpm run build\n\n# Create a .zip for Chrome Web Store\nnpm run package\n```\n\n### Development Commands\n\n```bash\n# Run extension in Chrome for development\nnpm start\n\n# Watch TypeScript files for changes\nnpm run watch\n\n# Clean build directory\nnpm run clean\n```\n\n### Available npm Scripts\n\n| Command | Description |\n|---------|-------------|\n| `npm run build` | Compiles TypeScript and copies assets to `dist/` directory |\n| `npm run package` | Builds and creates a `.zip` file ready for Chrome Web Store submission |\n| `npm start` | Builds and launches the extension in Chrome/Chromium for development |\n| `npm run watch` | Watches TypeScript files and recompiles on changes |\n| `npm run clean` | Removes the `dist/` build directory |\n| `npm run sync-version` | Syncs version from `package.json` to `manifest.json` (runs automatically during build) |\n\n### Installation in Chrome\n\n#### For Development (automatic)\n1. Run `npm start` to build and launch the extension in Chrome\n2. The extension will be automatically loaded and reloaded when you make changes\n3. Chrome will open with the extension pre-installed for testing\n\n#### For Development (manual)\n1. Run `npm run build` to compile the extension\n2. Open Chrome and navigate to `chrome://extensions`\n3. Enable Developer Mode by clicking the toggle switch\n4. Click \"Load unpacked\" and select the `dist/` directory\n\n#### For Chrome Web Store Publishing\n1. Run `npm run package` to create `ipfs-quicklaunch-{version}.zip`\n2. Upload the generated `.zip` file to [Chrome Web Store Developer Dashboard](https://chrome.google.com/webstore/developer/dashboard)\n\n\n\n## 🏗️ Architecture Overview\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                    Browser Extension                            │\n│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │\n│  │   Popup UI      │  │  Background     │  │ Content Script  │ │\n│  │                 │  │ Service Worker  │  │                 │ │\n│  │ • App Management│  │                 │  │ • Header Check  │ │\n│  │ • User Interface│  │ • DNSLink Probe │  │ • Page Context  │ │\n│  │ • Theme System  │  │ • Tab Monitoring│  │ • Same-Origin   │ │\n│  │ • Form State    │  │ • Icon Updates  │  │   Requests      │ │\n│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │\n│           │                     │                     │         │\n│           └─────────────────────┼─────────────────────┘         │\n│                                 │                               │\n│  ┌─────────────────────────────────────────────────────────────┐ │\n│  │                Chrome Storage API                           │ │\n│  │ • Apps \u0026 Versions    • Settings \u0026 Themes                   │ │\n│  │ • Gateway Config     • DNSLink Cache                       │ │\n│  └─────────────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────────┘\n                                 │\n                                 ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                    External Services                            │\n│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │\n│  │   DNS-over-     │  │  IPFS Gateways  │  │  Local IPFS     │ │\n│  │    HTTPS        │  │                 │  │    Gateway      │ │\n│  │                 │  │ • dweb.link     │  │                 │ │\n│  │ • DNSLink TXT   │  │ • inbrowser.*   │  │ • localhost:8080│ │\n│  │   Records       │  │ • Custom Gates  │  │ • Auto-detect   │ │\n│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n## 📁 Project Structure\n\n```\nsrc/\n├── manifest.json              # Extension manifest (v3)\n├── popup.html                 # Main UI (400px width, responsive)\n├── popup.ts                   # Popup controller \u0026 state management\n├── background.ts              # Service worker \u0026 tab monitoring\n├── content.ts                 # Content script for header detection\n├── components/\n│   ├── AppFlag.ts            # Individual app card component\n│   └── VersionManager.ts     # Version management modal\n├── storage/\n│   └── index.ts              # Storage management \u0026 caching\n├── types/\n│   └── index.ts              # TypeScript interfaces\n├── utils/\n│   ├── theme.ts              # Theme system \u0026 preferences\n│   ├── export.ts             # Data backup/restore\n│   ├── formState.ts          # Form auto-save \u0026 persistence\n│   ├── dnslink.ts            # DNSLink \u0026 x-ipfs-path detection\n│   ├── localGateway.ts       # Local IPFS gateway probing\n│   └── ipfs.ts               # IPFS utilities \u0026 CID validation\n└── icons/                    # Extension icons (16/48/128px)\n```\n\n## 🧠 Core Data Model\n\n```typescript\ninterface App {\n  id: string                    // Unique identifier\n  nickname: string             // User-chosen friendly name\n  description?: string         // Optional description\n  icon?: string               // Optional icon URL\n  versions: AppVersion[]      // Multiple versions per app\n  tags: string[]             // Categorization tags\n  createdAt: number         // Unix timestamp\n  lastUsed: number          // Unix timestamp\n}\n\ninterface AppVersion {\n  id: string                // Version identifier\n  name: string             // Version name (e.g., \"v1.2.0\")\n  cid: string             // IPFS CID (primary identifier)\n  hash?: string          // Legacy hash field\n  isDefault: boolean     // Default version flag\n  createdAt: number     // Unix timestamp\n}\n\ninterface GatewayConfig {\n  defaultGateway: string      // Domain for subdomain resolution\n  customGateways: string[]    // User-defined gateways\n  preferLocalGateway: boolean // Prefer localhost:8080\n  localGatewayUrl: string    // Local gateway URL\n}\n\ninterface DNSLinkCacheEntry {\n  domain: string              // Domain name\n  lastCID: string            // Last detected CID\n  lastChecked: number        // Cache timestamp\n  associatedAppId?: string   // Linked app ID\n}\n```\n\n## 🎯 Key Design Decisions\n\n### 1. **CID-Based Architecture**\n- **Decision**: Store IPFS CIDs instead of full URLs\n- **Rationale**: \n  - Gateway-agnostic: Users can switch gateways without losing data\n  - Future-proof: Works with any IPFS gateway or resolution method\n  - Efficient: Single CID maps to multiple possible URLs\n- **Implementation**: Dynamic URL construction at launch time\n\n### 2. **Dual Detection System**\n- **Decision**: Support both DNSLink TXT records and x-ipfs-path headers\n- **Rationale**:\n  - **DNSLink**: Standard IPFS name resolution via DNS\n  - **x-ipfs-path**: Gateway-served content detection\n  - **Coverage**: Captures more IPFS content types\n- **Implementation**: DNS-over-HTTPS + content script messaging\n\n### 3. **Store-Friendly Permissions**\n- **Decision**: Minimal permission set (storage, tabs, activeTab)\n- **Rationale**:\n  - **Fast approval**: Reduced review time for web stores\n  - **User trust**: Lower permission requests increase adoption\n  - **Security**: Principle of least privilege\n- **Trade-offs**: Limited to DNS-over-HTTPS vs. direct DNS access\n\n### 4. **Local-First Data Management**\n- **Decision**: Chrome Storage API with local caching\n- **Rationale**:\n  - **Privacy**: No external servers or analytics\n  - **Performance**: Local cache for instant access\n  - **Reliability**: Works offline\n- **Backup**: Export/import for data portability\n\n### 5. **Component-Based Architecture**\n- **Decision**: Modular TypeScript components\n- **Rationale**:\n  - **Maintainability**: Clear separation of concerns\n  - **Testability**: Isolated component logic\n  - **Reusability**: Components used across different contexts\n- **Structure**: AppFlag, VersionManager, Storage, Utils\n\n### 6. **Progressive Enhancement**\n- **Decision**: Graceful degradation for failed features\n- **Rationale**:\n  - **Reliability**: Core functionality works even if advanced features fail\n  - **Browser compatibility**: Different environments have different capabilities\n  - **User experience**: Never block the user due to edge cases\n- **Examples**: Content script fallbacks, local gateway detection\n\n### 7. **Modern Subdomain Gateway Support**\n- **Decision**: Prefer `https://{cid}.ipfs.{gateway}` over path-based URLs\n- **Rationale**:\n  - **Security**: Proper origin isolation for web apps\n  - **Performance**: Better caching and CDN support\n  - **Standards**: Aligns with modern IPFS gateway specifications\n- **Fallback**: Support for legacy path-based gateways\n\n### 8. **Real-Time State Management**\n- **Decision**: Live tab monitoring and app highlighting\n- **Rationale**:\n  - **Context awareness**: Show which app corresponds to current tab\n  - **User feedback**: Visual confirmation of saved apps\n  - **Discovery**: Help users connect URLs to saved apps\n- **Implementation**: Background tab monitoring + popup state sync\n\n## 🔧 Development Details\n\n### Build System\n- **TypeScript Compilation**: `tsc` with strict type checking\n- **Asset Pipeline**: Copy HTML, manifest, and icons to `dist/`\n- **Watch Mode**: Automatic rebuilds during development\n- **Zero Bundling**: Pure browser APIs, no webpack/rollup complexity\n\n### Performance Optimizations\n- **Local Caching**: Storage manager with in-memory cache\n- **Debounced Operations**: Form auto-save and search filtering\n- **Lazy Loading**: Components instantiated on demand\n- **Efficient Queries**: Indexed storage lookups by ID and CID\n\n### Browser Compatibility\n- **Manifest V3**: Modern Chrome extension standards\n- **ES2020+ Features**: Native modules, async/await, optional chaining\n- **Progressive Enhancement**: Core features work across different environments\n- **CORS Handling**: DNS-over-HTTPS and content script messaging\n\n### Security Considerations\n- **Content Security Policy**: Strict CSP for popup HTML\n- **Input Validation**: CID format validation and sanitization\n- **Origin Isolation**: Subdomain gateway URLs for proper app separation\n- **No External Dependencies**: Self-contained for supply chain security\n\n## 🧪 Testing \u0026 Quality\n\n### Type Safety\n- **Full TypeScript Coverage**: All source files typed\n- **Interface Definitions**: Comprehensive type definitions\n- **Strict Compilation**: `noImplicitAny`, `strictNullChecks` enabled\n\n### Error Handling\n- **Graceful Degradation**: Fallbacks for all external dependencies\n- **User Feedback**: Clear error messages and loading states\n- **Debug Logging**: Console logging for development and debugging\n- **Exception Safety**: Try-catch blocks around critical operations\n\n## 📦 Distribution\n\n### Chrome Web Store Ready\n- **Minimal Permissions**: Only `storage`, `tabs`, `activeTab`\n- **Privacy Compliant**: No external analytics or tracking\n- **Content Security Policy**: Strict CSP without `unsafe-eval`\n- **Manifest V3**: Future-proof extension format\n\n### Development Workflow\n```bash\n# Install dependencies\nnpm install\n\n# Development - launches in Chrome with auto-reload\nnpm start\n\n# Or watch TypeScript files for manual reload\nnpm run watch\n\n# Production build for testing\nnpm run build\n\n# Create .zip for Chrome Web Store\nnpm run package\n\n# Load dist/ folder in Chrome Developer Mode\nchrome://extensions/ -\u003e \"Load unpacked\"\n```\n\n## 🤝 Contributing\n\n### Code Style\n- **TypeScript**: Strict typing with interfaces\n- **Modern ES6+**: Arrow functions, destructuring, async/await\n- **Component Pattern**: Self-contained, reusable components\n- **Error-First**: Explicit error handling and user feedback\n\n### Architecture Principles\n1. **Separation of Concerns**: Clear boundaries between UI, storage, and utilities\n2. **Progressive Enhancement**: Core functionality always available\n3. **User Privacy**: Local-first data management\n4. **Performance**: Efficient caching and minimal network requests\n5. **Accessibility**: Keyboard navigation and screen reader support\n\n---\n\n**Built by [Shipyard](https://ipshipyard.com/) with ❤️ for the IPFS ecosystem**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipshipyard%2Fipfs-quicklaunch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipshipyard%2Fipfs-quicklaunch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipshipyard%2Fipfs-quicklaunch/lists"}