{"id":29119991,"url":"https://github.com/panphora/hyperclay-local","last_synced_at":"2025-08-23T16:14:05.474Z","repository":{"id":297874308,"uuid":"998167498","full_name":"panphora/hyperclay-local","owner":"panphora","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-18T10:18:36.000Z","size":473,"stargazers_count":29,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-18T12:21:11.966Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/panphora.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-06-08T02:26:33.000Z","updated_at":"2025-08-18T11:37:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"6c5dc496-4b6e-477c-963f-72a0badc8906","html_url":"https://github.com/panphora/hyperclay-local","commit_stats":null,"previous_names":["panphora/local-hyperclay","panphora/hyperclay-local"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/panphora/hyperclay-local","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/panphora%2Fhyperclay-local","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/panphora%2Fhyperclay-local/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/panphora%2Fhyperclay-local/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/panphora%2Fhyperclay-local/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/panphora","download_url":"https://codeload.github.com/panphora/hyperclay-local/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/panphora%2Fhyperclay-local/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270996772,"owners_count":24681937,"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-18T02:00:08.743Z","response_time":89,"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-06-29T14:06:00.042Z","updated_at":"2025-08-23T16:14:05.466Z","avatar_url":"https://github.com/panphora.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Hyperclay Local Server (Electron App)\n\nA beautiful, cross-platform desktop application for running your Hyperclay HTML apps locally with zero configuration.\n\n## ✨ Features\n\n- 🖥️ **Native desktop app** - Familiar GUI interface\n- 📁 **Visual folder selection** - Point and click to choose your apps folder\n- 🚀 **One-click server start** - Start/stop server with buttons\n- 🌐 **Auto-browser opening** - Automatically opens your default browser\n- 📊 **Real-time status** - Visual indicators for server state\n- 🔔 **System tray integration** - Runs in background, accessible from tray\n- 🎨 **Beautiful UI** - Modern, responsive interface\n- 🔗 **Quick links** - Easy access to Hyperclay.com and docs\n- ⚡ **Cross-platform** - Works on macOS, Windows, and Linux\n\n## What is Hyperclay?\n\nHyperclay lets you create **malleable HTML applications** - powerful, self-contained web apps that you fully own and control. Think of it as combining the simplicity of Google Docs with the power of custom web applications.\n\n### The Big Idea\n- **Own Your Stack**: No vendor lock-in. Download your apps and run them anywhere.\n- **Malleable**: Your HTML apps can modify themselves and save changes instantly.\n- **Shareable**: Send a link, and others can view or clone your app with one click.\n- **Future-Proof**: Built on standard HTML/CSS/JavaScript - no proprietary frameworks.\n\n### How Hyperclay Apps Work\n\n#### Self-Modifying HTML\nYour HTML applications can edit themselves in real-time. Change text, add features, modify layouts - everything saves automatically and becomes part of the app. Each app is a complete HTML document that includes:\n- Your content and data\n- Styling (CSS) \n- Behavior (JavaScript)\n- File references\n- Version metadata\n\n#### Edit Mode\nToggle edit mode by adding `?editmode=true` to any app URL or clicking the edit button. In edit mode:\n- Click any text to edit it inline\n- Add new elements and components\n- Upload files and images\n- Customize styling and behavior\n- Save changes instantly with Ctrl+S\n\n#### Examples You Can Build\n- **📝 Writer**: Personal writing app with auto-save, word count, and export options\n- **📋 Kanban Board**: Visual project management with drag-and-drop cards and columns\n- **🛠️ Development Log**: Track coding projects, bugs, features, and progress over time\n- **🏠 Landing Pages**: Beautiful pages for projects, products, or personal sites\n- **🎯 Custom Apps**: Calculators, games, portfolios, databases, dashboards - anything you can imagine\n\n### Why Use This Local Server?\n\nWhile [hyperclay.com](https://hyperclay.com) provides the full hosted experience with user accounts, version history, and collaboration features, this local server lets you:\n\n- ✅ **Work offline** - Edit your apps without internet connection\n- ✅ **Own your data** - Complete independence from any platform\n- ✅ **No subscription needed** - Run unlimited apps locally for free\n- ✅ **Privacy first** - Your apps and data never leave your computer\n- ✅ **Future-proof** - Apps work forever, regardless of service status\n\nThis local server provides the core functionality needed to run and edit your Hyperclay apps, ensuring you're never locked into any platform while still benefiting from the powerful malleable HTML concept.\n\n## 🚀 Quick Start\n\n### For Users (Download Pre-built App)\n\n1. **Download** the app for your platform:\n   - **macOS**: `Hyperclay-Local-1.0.0.dmg`\n   - **Windows**: `Hyperclay-Local-Setup-1.0.0.exe`\n   - **Linux**: `Hyperclay-Local-1.0.0.AppImage`\n\n2. **Install** and run the app\n\n3. **Select your folder** containing HTML apps\n\n4. **Click \"Start Server\"** \n\n5. **Browser opens** automatically to your apps!\n\n### For Developers (Build from Source)\n\n```bash\n# Install dependencies\nnpm install\n\n# Run in development mode\nnpm run dev\n\n# Build for all platforms\nnpm run build-all\n\n# Build for specific platform\nnpm run build-mac     # macOS\nnpm run build-windows # Windows  \nnpm run build-linux   # Linux\n```\n\n## 🎯 User Interface\n\n### Main Window\n- **Header**: Shows app name and server status indicator\n- **Folder Selection**: Visual folder picker with current selection display\n- **Server Controls**: Start/stop buttons and browser launcher\n- **Server Info**: Shows URL and folder path when running\n- **Instructions**: Step-by-step usage guide\n- **Quick Links**: Links to Hyperclay.com and documentation\n\n### System Tray\n- **Status indicator**: Green (running) / Red (stopped)\n- **Quick actions**: Start/stop server, show/hide window\n- **Background operation**: App continues running when window closed\n\n### Keyboard Shortcuts\n- `Cmd/Ctrl + O`: Select folder\n- `Cmd/Ctrl + R`: Start server\n- `Cmd/Ctrl + S`: Stop server\n- `Cmd/Ctrl + W`: Close window (app stays in tray)\n- `Cmd/Ctrl + Q`: Quit app (macOS only)\n\n## 🔧 How It Works\n\n### Server Integration\nThe app runs an embedded Express.js server (same as the Node.js version) with:\n- Static file serving with extensionless HTML support\n- POST `/save/:name` endpoint for app self-saving\n- Beautiful directory listings\n- Security protections (path traversal, filename validation)\n\n### File Management\n- **Folder Selection**: Native OS folder picker dialog\n- **Path Security**: Ensures all files served are within selected folder\n- **File Types**: Serves all file types, special handling for HTML\n- **Hidden Files**: Automatically hides dotfiles and system files\n\n### Browser Integration\n- **Auto-launch**: Opens default browser when server starts\n- **URL copying**: One-click copy of server URL\n- **External links**: Opens external links in default browser\n\n## 🛡️ Security Features\n\n- **Sandboxed renderer**: Web content runs in isolated context\n- **IPC security**: Secure communication between main and renderer processes\n- **Path validation**: Prevents access to files outside selected folder\n- **Filename sanitization**: Only allows safe characters in saved files\n- **Content validation**: Validates file content before saving\n\n## 📁 Project Structure\n\n```\nelectron/\n├── main.js              # Main Electron process\n├── server.js            # Express server implementation  \n├── preload.js           # Secure IPC bridge\n├── renderer.html        # Main UI\n├── renderer.css         # UI styling\n├── package.json         # Dependencies and build config\n├── assets/              # App icons and images\n└── dist/               # Built applications (after build)\n```\n\n## 🔧 Development\n\n### Prerequisites\n- Node.js 16+ \n- npm or yarn\n\n### Setup\n```bash\n# Install dependencies\nnpm install\n\n# Run in development mode (with hot reload)\nnpm run dev\n\n# Build for current platform\nnpm run build\n\n# Build for all platforms\nnpm run build-all\n```\n\n### Development Mode Features\n- **Hot reload**: Automatically restarts on file changes\n- **Developer tools**: Press F12 to open DevTools\n- **Debugging**: Full Chrome DevTools available\n\n## 📦 Building \u0026 Distribution\n\n### Build Configuration\nThe app uses `electron-builder` for packaging with these outputs:\n\n**macOS**:\n- `.dmg` installer with drag-to-Applications\n- Universal binary (Intel + Apple Silicon)\n- Code signing ready\n\n**Windows**:\n- NSIS installer with custom install directory option\n- Auto-updater support\n- Windows Store ready\n\n**Linux**:\n- AppImage (portable, runs anywhere)\n- Debian/Ubuntu packages available\n- Snap package support\n\n### Build Commands\n```bash\n# Development build (current platform)\nnpm run build\n\n# Production builds\nnpm run build-mac      # macOS DMG\nnpm run build-windows  # Windows installer\nnpm run build-linux    # Linux AppImage\nnpm run build-all      # All platforms\n```\n\n### Distribution Size\n- **macOS**: ~100MB DMG\n- **Windows**: ~76MB installer  \n- **Linux**: ~106MB AppImage\n\n## 🚨 Troubleshooting\n\n### Installation Issues\n\n**macOS \"App is damaged\" error**:\n```bash\nxattr -cr \"/Applications/Hyperclay Local.app\"\n```\n\n**Windows SmartScreen warning**:\n- Click \"More info\" → \"Run anyway\"\n- This happens because the app isn't code-signed\n\n**Linux permission denied**:\n```bash\nchmod +x Hyperclay-Local-1.0.0.AppImage\n```\n\n### Runtime Issues\n\n**Port 4321 already in use**:\n- The app will show an error dialog\n- Kill any existing process using the port\n- Or wait for the existing process to terminate\n\n**Folder selection not working**:\n- Ensure you have read permissions for the folder\n- Try selecting a different folder\n- Restart the app if the dialog doesn't appear\n\n**Server won't start**:\n- Check the folder contains some files\n- Ensure folder path doesn't contain special characters\n- Try selecting the folder again\n\n**Apps won't save**:\n- Check browser console for error messages\n- Ensure the app is making requests to `localhost:4321`\n- Verify the save endpoint is working by testing manually\n\n### Performance Issues\n\n**App feels slow**:\n- This is normal for Electron apps\n- Close other resource-intensive applications\n- Consider using the Go binary for better performance\n\n**High memory usage**:\n- Electron apps use more memory than native apps\n- ~100-200MB usage is normal\n- Restart the app if memory usage grows excessively\n\n## 🔮 Future Enhancements\n\nPlanned features for future versions:\n\n- **Auto-updater**: Automatic app updates\n- **Multiple servers**: Run multiple folders simultaneously  \n- **Custom ports**: Configure server port in settings\n- **HTTPS support**: Local SSL certificates\n- **File watcher**: Auto-refresh browser on file changes\n- **Themes**: Dark mode and custom themes\n- **Plugin system**: Extend functionality with plugins\n\n## 🤝 Contributing\n\nContributions welcome! Areas that need help:\n\n- **UI/UX improvements**: Better design and user experience\n- **Performance optimization**: Reduce app size and memory usage\n- **Cross-platform testing**: Ensure consistent behavior\n- **Documentation**: Improve guides and troubleshooting\n- **Feature requests**: Suggest and implement new features\n\n---\n\n**Made with ❤️ for Hyperclay** - The platform for malleable HTML applications  \nGet the full experience at [hyperclay.com](https://hyperclay.com)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpanphora%2Fhyperclay-local","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpanphora%2Fhyperclay-local","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpanphora%2Fhyperclay-local/lists"}