mirror of
https://github.com/samsonjs/vibetunnel.git
synced 2026-04-25 14:57:37 +00:00
improve custom node docs
This commit is contained in:
Peter Steinberger
parent
d54fd23dca
commit
8e527c3c97
3 changed files with 92 additions and 112 deletions
|
|
@ -1,96 +0,0 @@
|
|||
# Bun Server Support
|
||||
|
||||
VibeTunnel now includes support for running with Bun, a high-performance JavaScript runtime with built-in native module support.
|
||||
|
||||
## Architecture Considerations
|
||||
|
||||
**Important**: Bun does not support universal binaries. The Bun executable is architecture-specific and will be built for the native architecture during compilation. Despite this limitation, VibeTunnel still creates a universal binary for the main application, with the Bun executable being selected at runtime based on the current architecture.
|
||||
|
||||
## Features
|
||||
|
||||
- High-performance JavaScript/TypeScript execution
|
||||
- Built-in native module support (pty.node, spawn-helper)
|
||||
- Integrated `fwd` command for terminal forwarding
|
||||
- Smaller binary size compared to Node.js
|
||||
|
||||
## Building with Bun Support
|
||||
|
||||
### Automatic Build (Recommended)
|
||||
|
||||
The Bun executable is automatically built during the main build process. The build script:
|
||||
1. Detects the native architecture
|
||||
2. Builds the Bun executable for that architecture
|
||||
3. Embeds it into the universal app bundle
|
||||
|
||||
**Note**: Each build contains only the Bun executable for the build machine's architecture. For a true universal distribution, separate builds on Intel and Apple Silicon machines would need to be combined.
|
||||
|
||||
### Manual Build
|
||||
|
||||
If you need to build the Bun executable manually:
|
||||
|
||||
```bash
|
||||
cd web
|
||||
node build-native.js
|
||||
```
|
||||
|
||||
This creates:
|
||||
- `native/vibetunnel` - The Bun executable
|
||||
- `native/pty.node` - Native PTY module
|
||||
- `native/spawn-helper` - Helper binary for spawning processes
|
||||
|
||||
### Verification
|
||||
|
||||
To verify Bun support is properly built:
|
||||
|
||||
```bash
|
||||
# Check if files exist
|
||||
ls -la web/native/
|
||||
|
||||
# Test the executable
|
||||
web/native/vibetunnel --version
|
||||
```
|
||||
|
||||
## CLI Usage
|
||||
|
||||
When using the Bun server, the `vt` command automatically prepends `fwd`:
|
||||
|
||||
```bash
|
||||
# With Go server:
|
||||
vt mycommand # → vibetunnel mycommand
|
||||
|
||||
# With Bun server:
|
||||
vt mycommand # → vibetunnel fwd mycommand
|
||||
```
|
||||
|
||||
## Switching Between Servers
|
||||
|
||||
You can switch between Go and Bun servers in Settings → Debug → Server Type.
|
||||
|
||||
When switching, you may need to reinstall the CLI tools to update the `vt` wrapper script.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Bun server is not available"
|
||||
|
||||
This error means the Bun executable or native modules are missing. Solutions:
|
||||
|
||||
1. Ensure the build script runs: Check Xcode build logs for "Build Bun Executable"
|
||||
2. Build manually: `cd web && node build-native.js`
|
||||
3. Verify files: Check `VibeTunnel.app/Contents/Resources/` for:
|
||||
- vibetunnel (60MB executable)
|
||||
- pty.node
|
||||
- spawn-helper
|
||||
|
||||
### CLI not working after switching
|
||||
|
||||
After switching server types, reinstall the CLI tools:
|
||||
1. Settings → Advanced → Reinstall CLI Tools
|
||||
2. Enter admin password when prompted
|
||||
3. The installer will create the appropriate `vt` script/symlink
|
||||
|
||||
## Development
|
||||
|
||||
The Bun server code is in:
|
||||
- `mac/VibeTunnel/Core/Services/BunServer.swift` - Swift integration
|
||||
- `web/src/server/` - JavaScript server implementation
|
||||
- `web/build-native.js` - Build script for creating the Bun executable
|
||||
|
|
@ -3,23 +3,12 @@
|
|||
/**
|
||||
* Build a custom Node.js binary with reduced size by excluding features we don't need.
|
||||
*
|
||||
* This creates a Node.js build without:
|
||||
* - International support (ICU) - saves ~28MB
|
||||
* - npm/npx - saves ~5MB
|
||||
* - corepack
|
||||
* - dtrace/etw instrumentation
|
||||
* See custom-node.md for detailed documentation, usage, and troubleshooting.
|
||||
*
|
||||
* The resulting binary is typically 50-60MB instead of 110+MB.
|
||||
*
|
||||
* Usage:
|
||||
* ```bash
|
||||
* node build-custom-node.js # Build for current Node.js version
|
||||
* node build-custom-node.js --latest # Build latest Node.js version
|
||||
* node build-custom-node.js --version=24.2.0 # Build specific version
|
||||
* ```
|
||||
*
|
||||
* The custom Node.js will be built in:
|
||||
* .node-builds/node-vXX-minimal/out/Release/node
|
||||
* Quick usage:
|
||||
* node build-custom-node.js # Current version
|
||||
* node build-custom-node.js --latest # Latest version
|
||||
* node build-custom-node.js --version=24.1.0 # Specific version
|
||||
*/
|
||||
|
||||
const { execSync } = require('child_process');
|
||||
|
|
|
|||
87
web/custom-node.md
Normal file
87
web/custom-node.md
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
# Custom Node.js Build
|
||||
|
||||
This document describes how to build a minimal custom Node.js binary for VibeTunnel.
|
||||
|
||||
## Overview
|
||||
|
||||
The custom Node.js build reduces binary size from ~110MB to ~50-60MB by excluding:
|
||||
- International support (ICU) - saves ~28MB
|
||||
- npm/npx - saves ~5MB
|
||||
- corepack
|
||||
- dtrace/etw instrumentation
|
||||
- Inspector protocol
|
||||
- Other unused features
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Build for current Node.js version
|
||||
node build-custom-node.js
|
||||
|
||||
# Build latest Node.js version
|
||||
node build-custom-node.js --latest
|
||||
|
||||
# Build specific version
|
||||
node build-custom-node.js --version=24.1.0
|
||||
node build-custom-node.js --version=24.2.0
|
||||
```
|
||||
|
||||
## Output Location
|
||||
|
||||
The custom Node.js will be built in:
|
||||
```
|
||||
.node-builds/node-vXX-minimal/out/Release/node
|
||||
```
|
||||
|
||||
## Build Requirements
|
||||
|
||||
- Python 3 (for Node.js build system)
|
||||
- C++ compiler (Xcode command line tools on macOS)
|
||||
- make
|
||||
- ~10-20 minutes build time
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Incomplete Builds
|
||||
|
||||
If builds are incomplete (directories exist but no executable):
|
||||
|
||||
```bash
|
||||
# Delete the incomplete build
|
||||
rm -rf .node-builds/node-v24.1.0-minimal
|
||||
|
||||
# Rebuild
|
||||
node build-custom-node.js --version=24.1.0
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
- **Interrupted builds**: Delete the directory and rebuild
|
||||
- **Missing executable**: Check `.node-builds/node-vXX-minimal/out/Release/node` exists
|
||||
- **Build failures**: Ensure Xcode command line tools are installed (macOS)
|
||||
- **Build time**: The build process takes 10-20 minutes - let it complete fully
|
||||
|
||||
### Verification
|
||||
|
||||
After building, verify the executable exists:
|
||||
```bash
|
||||
ls -la .node-builds/node-v24.1.0-minimal/out/Release/node
|
||||
```
|
||||
|
||||
## Using with build-native.js
|
||||
|
||||
The custom Node.js is automatically detected by `build-native.js`:
|
||||
|
||||
```bash
|
||||
# Auto-detect latest custom build
|
||||
node build-native.js --custom-node
|
||||
|
||||
# Specify custom Node path
|
||||
node build-native.js --custom-node=/path/to/custom/node
|
||||
```
|
||||
|
||||
## Size Comparison
|
||||
|
||||
- Standard Node.js: ~110MB
|
||||
- Custom Node.js: ~50-60MB
|
||||
- Final executable with custom Node: ~105MB (vs ~155MB with standard Node)
|
||||
Loading…
Reference in a new issue