💻 forward (CLI: fwd)

Isolated, throwaway runtime for modern frontend projects No node_modules, no pollution — just run, dev, and it disappears.

⚠️ Important: Forward (fwd) is not a package manager. It's a command forwarding tool that creates temporary environments with isolated node_modules for your commands. It doesn't manage your project's dependencies permanently.

✨ Features

• 🧼 Run any project without installing deps locally
• 🧪 Use vite, react-scripts, next, etc. with hot reload
• 🔐 Dependencies are installed in a temp session, never your project
• 🗑️ When the server stops, everything is cleaned
• 🧙 Supports install, uninstall, and custom commands
• 🌐 Run remote repositories directly with --repository
• 🔒 HTTPS support with automatic SSL certificates
• 📊 Inspect and manage node_modules with modules commands

🚀 Quick Start

npm install -g @bourgils/forward

Inside a project with a package.json

fwd env init      # Initialize environment and detect pipe & package manager
fwd env show      # Show current environment configuration
fwd env set       # Set specific environment configuration
fwd env reset     # Reset environment to default state
fwd doctor        # Check system compatibility and configuration
fwd dev           # → vite dev or next dev
fwd run build     # → npm run build (in temp env)
fwd exec echo Hello
fwd add react react-dom
fwd remove react

Run remote repositories

fwd run dev --repository=https://github.com/user/repo
fwd run dev --repository=https://github.com/user/repo --keep-clone  # Keep the clone after execution

Run with HTTPS

sudo fwd run dev --https
sudo fwd run dev --https --domain=custom-domain.com

Manage node_modules

fwd modules inspect . --also dist,build,.*cache  # Show node_modules content and size
fwd modules prune    # Clean up unused dependencies

🔧 CLI Commands

| Command | Alias | Description | | ---------------------------- | ----------- | ----------------------------------------------------------- | | fwd env init | i | Initialize environment and detect pipe & pkg manager | | fwd env show | s | Show current environment configuration | | fwd env set | | Set specific environment configuration | | fwd env reset | r | Reset environment to default state | | fwd doctor | d | Check system compatibility and configuration | | fwd run [script] | | Run npm script from package.json | | fwd exec [cmd] [args...] | | Execute any raw command in session | | fwd add [package] | install | Add a package | | fwd remove [package] | uninstall | Remove a package | | fwd modules inspect [root] | | Inspect node_modules content and size from [root] directory | | fwd modules prune [root] | | Clean up unused dependencies from [root] directory |

run Command Options

| Option | Description | | ------------------- | --------------------------------------------------------------- | | --repository | Run from a remote repository (auto-clone & cleanup) | | -k, --keep-clone | Keep the cloned repository after execution, in current location | | -h, --https | Enable HTTPS with automatic trsuted SSL certificates | | -d, --domain | Set custom domain for HTTPS (default: .dev) | | -t, --target-port | Choose target port to forward traffic to (only with --https) |

modules inspect Command Options

| Option | Description | | -------------------- | ---------------------------------------------------------------------------------- | | -i, --ignore-paths | Add paths to ignore during inspection | | -a, --also | Add some files or folders to looking for during inspection (eg, --also build,dist) | | --all | Remove system paths and hidden files from default ignored paths |

modules prune Command Options

| Option | Description | | -------------------- | --------------------------------------------------------------- | | -i, --ignore-paths | Add paths to ignore for prune (eg, --ignore-paths ~/me,~/prod ) | | -a, --also | Add some files or folders to to prune (eg, --also build,dist) | | -y, --yes | Prevent prompt before prune files | | --dry-run | Dry run the command | | --interactive | Allow path selection for prune |

⚠️ Important: Please note that HTTPS support may require using the --target-port option in cases where concurrent processes are launched at startup and the detected port is not the target local server port. Additionally, hot-reload support with HTTPS may require configuration to forward WebSocket connections to the final server (e.g., for create-react-app (CRA), WDS_SOCKET_PORT=443 must be set in .env).

📁 How it works

• Creates an isolated environment for your project
• Manages dependencies in a temporary location
• Provides runtime checks for compatibility
• Launches your scripts as you usually do or any raw command
• Cleans everything after Ctrl+C
• Supports remote repository execution with automatic cleanup, HTTPS proxy for local development and

Environment not detected? Just use: fwd env set

🔒 HTTPS Support

⚠️ Important:

• The --https option requires sudo privileges: sudo fwd run dev --https
• During first run, the SSL certificate will be added to your keychain and macOS may prompt for your password
• HTTPS support is fully tested on macOS and implemented (untested) on Linux

Run any command with HTTPS support:

# Run dev script with default .dev domain (e.g., 357289.my-project.dev)
sudo fwd run dev --https

# Run dev script with custom domain
sudo fwd run dev --https --domain=awesome-app.dev

Mapping a .com, .net, .io, etc., which is probably a real domain, generates a warning. You can continue, but your browser's cache may cause problems.

Hot Reload Support

Hot reload is fully supported with the following configurations:

• Vite: Works out of the box
• Create React App: Requires a .env file with WDS_SOCKET_PORT=443 for hot reload support
• Others (Next.js, etc.): Support may vary depending on the framework's configuration

Note: The HTTPS proxy defaults map your project to a .dev domain (e.g., 357289.my-project.dev)

💡 Why?

Because node_modules folders are huge. And every time you clone a project, you run npm install and forget to clean. With fwd, you just run it and forget it — nothing is written in your project unless you want it.

🔄 Dev mode

Want to test locally?

git clone https://github.com/bourgils/forward
cd
cp .env.local .env # For CRA HTTPS support
npm install
npm link

Then go into any project and run:

fwd env init
fwd run dev or fwd run start

🫶 Author

Made with ❤️ by @bourgils

🗺️ Roadmap

The roadmap is currently open for suggestions! Here are some planned improvements:

🧠 Planned Features

• 🔍 Add ESLint plugin for consistent code style
• 🔒 Add pre-commit hooks for code validation
• More coming soon...

Feel free to:

• Open an issue with your feature request
• Join the discussion about the future of Forward
• Share your use cases and needs

Previous roadmap items completed in v0.5.0:

• 🧹 Code cleanup & architecture: refactor into classes/services for better structure
• 🌐 Remote execution UX: support for running remote repositories