💻 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

run Command Options

modules inspect Command Options

modules prune Command Options

⚠️ 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