Vite Plugin SSH Tunnel Advanced

A Vite plugin to easily create an SSH tunnel from your local development server to a remote server. This allows you to expose your local Vite dev server (e.g., localhost:5173) on a port on a remote machine, making it accessible via the remote machine's IP or a domain pointing to it.

This plugin uses the system's ssh command-line utility to establish and manage the tunnel.

Features

• Sets up an SSH reverse tunnel (ssh -R).
• Uses a private key for authentication.
• Automatically manages the tunnel lifecycle with the Vite dev server.
• Gracefully closes the tunnel on server shutdown or process exit.
• Configurable remote port.
• Option to display a custom proxy URL in logs.
• Colored logging for better readability.

Prerequisites

• SSH Client: An SSH client must be installed and available in your system's PATH.
  • Linux/macOS: Usually available by default.
  • Windows: OpenSSH client is often included in modern Windows 10/11 versions or can be installed with Git for Windows.
• SSH Server Configuration:
  • The remote SSH server must be configured to allow TCP forwarding. Ensure AllowTcpForwarding yes (or AllowTcpForwarding all) is set in your server's /etc/ssh/sshd_config.
  • For the remote port to be accessible from external networks (not just localhost on the remote server), GatewayPorts yes or GatewayPorts clientspecified must be set in /etc/ssh/sshd_config on the remote server. Restart the sshd service after changes.

Installation

npm install vite-plugin-ssh-tunnel-advanced --save-dev
# or
yarn add vite-plugin-ssh-tunnel-advanced --dev
# or
pnpm add vite-plugin-ssh-tunnel-advanced --save-dev

You might also need picocolors if not already present (though often a transitive dependency):

npm install picocolors

Usage

Import and add the plugin to your vite.config.js or vite.config.ts:

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react'; // Example, use your framework plugin
import { sshTunnel } from 'vite-plugin-ssh-tunnel-advanced';

export default defineConfig({
  plugins: [
    react(),
    sshTunnel({
      host: 'your-remote-server.com',    // SSH server address
      username: 'ssh_user',               // SSH username
      privateKey: '~/.ssh/id_rsa_remote', // Path to your SSH private key
      remotePort: 9000,                   // Port to listen on the remote server
      // Optional: If you access the tunnel via a custom domain/proxy
      // proxyUrl: 'https://dev.your-app.com'
    }),
  ],
});

When you run your Vite dev server (npm run dev or yarn dev), the plugin will:

1. Wait for the Vite server to start listening.
2. Attempt to establish an SSH tunnel to your remote server.
3. Traffic to your-remote-server.com:9000 (or your proxyUrl) will be forwarded to your local Vite dev server.

Configuration

The sshTunnel plugin accepts a configuration object with the following properties:

| Option | Type | Required | Default | Description | |--------------|----------|----------|---------|-------------------------------------------------------------------------------------------------------------------------------------------| | host | string | Yes | | SSH server host address (e.g., 'example.com', '192.168.1.100'). | | username | string | Yes | | Username for the SSH connection (e.g., 'root', 'deploy_user'). | | privateKey | string | Yes | | Path to the SSH private key file. Can use ~ for home directory (e.g., '~/.ssh/id_rsa'). | | remotePort | number | No | 3000 | Remote port on the SSH server to listen on. Traffic to this port will be forwarded to the local Vite server. | | proxyUrl | string | No | | Optional URL to display in logs after tunnel setup. Useful if the remote server is accessed via a domain/proxy (e.g., 'https://dev.example.com'). |

How it Works

The plugin executes a command similar to this:

ssh -i "<privateKeyPath>" \
    -o ExitOnForwardFailure=yes \
    -o ServerAliveInterval=30 \
    -o ServerAliveCountMax=3 \
    -f -N -M -S "<socketPath>" \
    -R 0.0.0.0:<remotePort>:localhost:<localVitePort> \
    <username>@<host>

• -R 0.0.0.0:<remotePort>:localhost:<localVitePort>: Sets up remote port forwarding.
• -M -S <socketPath>: Uses SSH ControlMaster for managing the connection via a socket file, allowing for clean termination.
• -f -N: Runs SSH in the background and prevents execution of remote commands.

Troubleshooting

• "Private key file not found":
  • Ensure the path provided in privateKey is correct.
  • The plugin resolves ~ to your home directory.
  • Check file permissions.
• "Failed to create SSH tunnel" / SSH stderr output:
  • Permission denied (publickey):
    • Verify the private key is authorized on the remote server for the specified user (i.e., its corresponding public key is in ~/.ssh/authorized_keys on the server).
    • Check permissions of your ~/.ssh directory (should be 700) and ~/.ssh/authorized_keys (should be 600 or 644) on the server.
  • Connection refused/timeout:
    • Ensure the host is correct and the SSH server is running and accessible.
    • Check firewalls (both local and on the remote server).
  • "Warning: remote port forwarding failed for listen port ":
    • The remotePort might already be in use on the remote server. Try a different port.
    • AllowTcpForwarding might be disabled on the server.
• Tunnel connects, but proxyUrl or http://<host>:<remotePort> doesn't work:
  • Ensure GatewayPorts yes (or clientspecified) is set in the remote server's sshd_config if you want to access the remotePort from outside the remote server's localhost.
  • Check firewalls on the remote server that might be blocking incoming connections to remotePort.
  • If using a domain/proxy (like Nginx), ensure it's correctly configured to forward traffic to localhost:<remotePort> on the remote server.

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check issues page.

License

This project is MIT licensed.