{"id":17285,"library":"local-ssl-proxy","title":"Simple Local HTTPS Proxy","description":"local-ssl-proxy is a lightweight utility designed to create an HTTPS proxy for local development. It leverages a self-signed SSL certificate, allowing developers to access local HTTP servers over HTTPS. This functionality is critical for testing applications that require a secure context, such as those using OAuth, secure cookies, geolocation APIs, or needing to avoid mixed-content warnings. The current stable version is 2.0.5, last updated in March 2023. While specific release cadence isn't formalized, updates typically address dependencies or minor enhancements. Its primary differentiators are its ease of use via the command line for quick setup, support for custom certificates (e.g., generated by `mkcert` for a trusted browser experience), and the ability to manage multiple proxy configurations through a single file, making it a flexible choice for diverse local development workflows. It is strictly intended for local development and should never be used in production environments.","status":"active","version":"2.0.5","language":"javascript","source_language":"en","source_url":"http://github.com/cameronhunter/local-ssl-proxy","tags":["javascript"],"install":[{"cmd":"npm install local-ssl-proxy","lang":"bash","label":"npm"},{"cmd":"yarn add local-ssl-proxy","lang":"bash","label":"yarn"},{"cmd":"pnpm add local-ssl-proxy","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Recommended for generating locally trusted SSL certificates to avoid browser warnings during development.","package":"mkcert","optional":true}],"imports":[{"note":"The primary way to use this package is via its command-line interface. `npx` is recommended for on-demand use, or `npm install -g local-ssl-proxy` for global installation.","wrong":"local-ssl-proxy","symbol":"CLI usage","correct":"npx local-ssl-proxy --source 9001 --target 9000"},{"note":"While primarily a CLI tool, the package exports a `start` function for programmatic control. This is useful for integrating the proxy into build scripts or other Node.js applications.","wrong":null,"symbol":"start","correct":"import { start } from 'local-ssl-proxy';\n// or\nconst { start } = require('local-ssl-proxy');"}],"quickstart":{"code":"import { start } from 'local-ssl-proxy';\nimport http from 'http';\n\n// Start a simple HTTP server on port 3000\nconst httpServer = http.createServer((req, res) => {\n  res.writeHead(200, { 'Content-Type': 'text/plain' });\n  res.end('Hello from HTTP server on port 3000!');\n});\nhttpServer.listen(3000, () => {\n  console.log('HTTP server running on http://localhost:3000');\n});\n\n// Start local-ssl-proxy to proxy HTTPS (9001) to HTTP (3000)\n// You'll likely need to generate trusted certs with mkcert first:\n// mkcert -install && mkcert localhost\nstart({\n  source: 9001,\n  target: 3000,\n  key: 'localhost-key.pem', // Path to your generated key\n  cert: 'localhost.pem'   // Path to your generated cert\n})\n  .then(() => {\n    console.log('HTTPS proxy running on https://localhost:9001');\n    console.log('Access your HTTP server via https://localhost:9001');\n  })\n  .catch(err => {\n    console.error('Failed to start proxy:', err.message);\n    process.exit(1);\n  });\n\n// CLI equivalent (run in terminal):\n// npx local-ssl-proxy --source 9001 --target 3000 --key localhost-key.pem --cert localhost.pem","lang":"typescript","description":"This example demonstrates how to programmatically start `local-ssl-proxy` to proxy HTTPS traffic from port 9001 to an underlying HTTP server on port 3000. It also shows the equivalent CLI command. This setup is ideal for local development and requires pre-generated `mkcert` certificates for a trusted experience."},"warnings":[{"fix":"Refer to the `local-ssl-proxy` GitHub repository or npm page for specific version documentation. It is generally recommended to use the latest stable version and update your scripts accordingly.","message":"Older versions of `local-ssl-proxy` might have different command-line arguments or configuration options. Ensure you are using the correct syntax for version 2.x, as breaking changes can occur between major releases (e.g., v1 to v2).","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"To avoid browser warnings, install `mkcert` (e.g., `brew install mkcert` on macOS, `choco install mkcert` on Windows), run `mkcert -install`, and then `mkcert localhost`. Configure `local-ssl-proxy` to use these generated `localhost.pem` and `localhost-key.pem` files with the `--cert` and `--key` flags.","message":"The proxy uses self-signed certificates by default, which will trigger browser security warnings (e.g., 'Your connection is not private'). While safe for local development, this can be disruptive.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"NEVER use `local-ssl-proxy` in production. For production HTTPS, always use professionally issued certificates from trusted Certificate Authorities (e.g., Let's Encrypt) and dedicated reverse proxies like Nginx or Caddy.","message":"This tool is strictly for local development environments. Using `local-ssl-proxy` with its self-signed certificates or for untrusted domains in production or publicly accessible environments poses severe security risks, including vulnerability to Man-in-the-Middle attacks.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always refer to the official documentation for the correct config file schema. An example structure includes objects where keys are proxy names, and values are objects with `source`, `target`, `key`, `cert`, and `hostname` properties.","message":"When using `local-ssl-proxy` to handle multiple proxy configurations via a JSON config file, ensure the file format precisely matches the expected structure. Incorrect keys or values can lead to unexpected behavior or proxy failure.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Accept the warning and proceed (for temporary testing) or, for a better development experience, use `mkcert` to generate locally trusted certificates and configure `local-ssl-proxy` to use them.","cause":"The browser does not trust the self-signed certificate generated by `local-ssl-proxy` by default.","error":"ERR_CERT_AUTHORITY_INVALID / NET::ERR_CERT_AUTHORITY_INVALID"},{"fix":"Choose a different available port for the `source` or `target` (e.g., `--source 9443` or `--target 8000`). You can identify the process using the port with `lsof -i :<port>` on Unix-like systems or `netstat -ano | findstr :<port>` on Windows.","cause":"The specified `source` or `target` port is already being used by another process on your system.","error":"Error: listen EADDRINUSE: address already in use :::<port>"},{"fix":"Ensure your HTTP application is actively running and listening on the `target` port specified for `local-ssl-proxy`. Check your firewall settings to allow traffic on both the `source` and `target` ports.","cause":"The backend HTTP server is not running on the `target` port, or there's a firewall blocking the connection between the proxy and the target server.","error":"Proxy is not redirecting or connection refused on target port"}],"ecosystem":"npm","meta_description":null}