Development Guide
Setup
Prerequisites
- macOS 14.0+
- Xcode 16.0+
- Node.js 18+
- Bun 1.0+
Clone & Build
Project Structure
Code Patterns
Swift (macOS/iOS)
Observable PatternTypeScript (Web)
Service ClassesDevelopment Workflow
Hot Reload Setup
Web DevelopmentTesting
Unit TestsDebugging
View LogsCommon Tasks
Add New API Endpoint
- Define in
web/src/server/routes/api.ts
- Add types in
web/src/shared/types.ts
- Update client in
web/src/client/services/api.ts
- Add tests in
web/tests/api.test.ts
Add New Menu Item
- Update
mac/VibeTunnel/Presentation/MenuBarView.swift
- Add action in
mac/VibeTunnel/Core/Actions/
- Update settings if needed
Modify Terminal Protocol
- Update
web/src/server/services/buffer-aggregator.ts
- Modify
web/src/client/services/websocket.ts
- Test with
web/tests/protocol.test.ts
Build System
macOS Build
Web Build
Release Build
Code Quality
Linting
Formatting
Performance
Profiling
Optimization Tips
- Use binary protocol for terminal data
- Batch WebSocket messages (16ms intervals)
- Lazy load terminal sessions
- Cache static assets with service worker
Troubleshooting
Issue | Solution |
---|---|
Port in use | lsof -i :4020 then kill process |
Build fails | Clean: rm -rf node_modules dist |
Tests fail | Check Node/Bun version |
Hot reload broken | Restart dev server |
Contributing
- Fork repository
- Create feature branch
- Follow code style
- Add tests
- Update documentation
- Submit PR