{"id":11061,"library":"https-localhost","title":"HTTPS Server for Localhost","description":"https-localhost is a lightweight utility designed to quickly establish an HTTPS server on localhost, featuring HTTP/2 and SSL via locally-trusted development certificates. It simplifies local development by eliminating the need for manual certificate generation and trust setup, supporting MacOS, Linux, and Windows, and working seamlessly with Chrome and Firefox. The current stable version is 4.7.1, with minor updates released periodically. It functions both as a standalone command-line tool for serving static files and as an importable module for Express.js applications or other web frameworks, offering unique ease-of-use for secure local development environments. Its key differentiator is the zero-configuration approach to trusted local SSL, integrating with `mkcert` under the hood. The project is currently seeking maintainers and contributors.","status":"maintenance","version":"4.7.1","language":"javascript","source_language":"en","source_url":"https://github.com/daquinoaldo/https-localhost","tags":["javascript","localhost","https","http2","https-server","SSL","express","expressjs","express-js"],"install":[{"cmd":"npm install https-localhost","lang":"bash","label":"npm"},{"cmd":"yarn add https-localhost","lang":"bash","label":"yarn"},{"cmd":"pnpm add https-localhost","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required on MacOS and Linux for Firefox and Chrome to trust locally generated certificates. It's a system-level dependency.","package":"nss","optional":false},{"reason":"Alternative to 'nss' on Linux distributions for Firefox and Chrome certificate trust. It's a system-level dependency.","package":"libnss3-tools","optional":false}],"imports":[{"note":"The package primarily uses CommonJS `require()`. The main export is a function that can be called to create an Express app instance or configure certificates for a specific domain. Direct ESM `import` is not officially documented or supported, and may lead to issues.","wrong":"import createHttpsServer from 'https-localhost';","symbol":"default export (function)","correct":"const createHttpsServer = require('https-localhost');"},{"note":"Calling the default exported function without arguments returns an Express application instance pre-configured for HTTPS. If passing a domain string, it configures for that domain.","wrong":"import { app } from 'https-localhost';","symbol":"Express app instance","correct":"const app = require('https-localhost')();"},{"note":"The `getCerts` method is an asynchronous function available on the Express app instance returned by the package's default export. It allows using the generated certificates with other Node.js HTTP servers.","wrong":"import { getCerts } from 'https-localhost';","symbol":"getCerts","correct":"const createHttpsServer = require('https-localhost'); const serverInstance = createHttpsServer(); const certs = await serverInstance.getCerts();"}],"quickstart":{"code":"const httpsLocalhost = require(\"https-localhost\");\nconst app = httpsLocalhost(); // Creates an Express app with local HTTPS\nconst port = process.env.PORT || 4433; // Default to 443 for HTTPS, using 4433 to avoid root permissions\n\n// Create a 'public' directory and add some static files for testing\n// e.g., echo '<h1>Hello, HTTPS!</h1>' > public/index.html\n\n// Serve static files from a 'public' directory\n// Ensure 'public' directory exists in your project root for this to work\napp.serve(`${__dirname}/public`);\n\n// Optionally redirect HTTP traffic to HTTPS (on the same port by default)\n// app.redirect();\n\napp.listen(port, () => {\n  console.log(`HTTPS server listening on https://localhost:${port}`);\n  console.log(`Serving static files from ${__dirname}/public`);\n});\n\n// Example of creating certificates for an additional domain and using them directly\nasync function demonstrateCustomCerts() {\n  // Pass a domain string to the main function to generate certificates for it\n  const customHttpsServer = httpsLocalhost(\"mycustomdomain.com\");\n  try {\n    const customCerts = await customHttpsServer.getCerts();\n    console.log(\"\\nCustom certificates generated for mycustomdomain.com:\");\n    console.log(\"  Certificate present:\", !!customCerts.cert);\n    console.log(\"  Key present:\", !!customCerts.key);\n    // You can now use customCerts with Node's native https.createServer\n    // Example: https.createServer(customCerts, someOtherApp).listen(8443);\n  } catch (error) {\n    console.error(\"Error generating custom certificates:\", error.message);\n  }\n}\ndemonstrateCustomCerts();","lang":"javascript","description":"Demonstrates how to initialize an HTTPS server with Express.js, serve static files, and obtain generated certificates for custom use, utilizing environment variables for port configuration."},"warnings":[{"fix":"Do not deploy applications using `https-localhost` to production. Use appropriate certificate management and server configurations for live environments.","message":"The package explicitly states it is 'not a production tool' and should be installed as a dev dependency. It's intended solely for local development environments.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Upgrade to `https-localhost@4.2.0` or newer to ensure compatibility with macOS Catalina and subsequent macOS versions.","message":"Earlier versions (prior to v4.2.0) had compatibility issues with macOS Catalina due to underlying `mkcert` versions, potentially preventing certificate generation or trust.","severity":"breaking","affected_versions":"<4.2.0"},{"fix":"When installing globally (`npm i -g`) or running the standalone CLI, use `sudo`. Alternatively, configure the server to listen on a non-privileged port (e.g., `PORT=4433`) to avoid requiring root access for the server process.","message":"On Linux and MacOS, installing or running `https-localhost` (especially on default ports 80/443 or during initial certificate generation) may require `sudo` permissions, which can lead to permission errors if not provided.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Evaluate this factor when considering long-term reliance on the package for critical development workflows. Consider contributing or exploring alternatives if sustained active development is a strict requirement.","message":"The project is explicitly 'looking for maintainers and contributors', indicating that future development, bug fixes, and long-term support might be limited or slow.","severity":"gotcha","affected_versions":">=4.7.1"},{"fix":"Update to `https-localhost@4.4.2` or newer to resolve issues related to Windows usernames with spaces.","message":"Prior to version 4.4.2, there were known issues with the package operating correctly on Windows systems where the user's username contained spaces.","severity":"breaking","affected_versions":"<4.4.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run the installation or the `https-localhost` command with `sudo`, e.g., `sudo npm i -g https-localhost` or `sudo serve ~/myproj`.","cause":"The package attempts to create or manage certificates in system-level directories that require elevated permissions (e.g., in macOS or Linux).","error":"Error: EACCES: permission denied, mkdir '/root/.local/share/mkcert'"},{"fix":"Ensure `nss` or `libnss3-tools` are installed (for Firefox/Chrome). For specific domain issues, regenerate certificates using `require(\"https-localhost\")(\"yourdomain.com\")`. To force a reinstall of the CA, use the `REINSTALL=true` environment variable: `REINSTALL=true serve ~/myproj`.","cause":"The locally generated certificate is not trusted by the browser, often because the root CA was not properly installed or renewed, or the domain requested does not match the certificate.","error":"NET::ERR_CERT_AUTHORITY_INVALID in browser"},{"fix":"Always use `const createServer = require('https-localhost');` or `const app = require('https-localhost')();` with CommonJS `require()` syntax.","cause":"Attempting to use ES module `import` syntax or destructuring when the package only exports a function via CommonJS `module.exports`.","error":"TypeError: require(...) is not a function"},{"fix":"Verify that the directory specified in `app.serve(path)` exists relative to your application's entry point, or provide an absolute path.","cause":"The path provided to `app.serve()` for static files does not exist on the filesystem.","error":"Error: ENOENT: no such file or directory, stat '/path/to/nonexistent/public'"}],"ecosystem":"npm"}