bourgils💻 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_modulesfor 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/forwardInside 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 reactRun 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 executionRun with HTTPS
sudo fwd run dev --https
sudo fwd run dev --https --domain=custom-domain.comManage 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
--httpsoption requiressudoprivileges: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.devMapping 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
.envfile withWDS_SOCKET_PORT=443for 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
.devdomain (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 linkThen 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