Registry / devops / https-localhost

https-localhost

JSON →
library4.7.1jsnpmunverified

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.

npm install https-localhost
INSTALL
IMPORT
SIG · HTTPS-LOCALHOST
H
https-localhost
devopsjavascriptv4.7.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

default export (function)
const createHttpsServer = require('https-localhost');
import createHttpsServer from 'https-localhost';
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.
Express app instance
const app = require('https-localhost')();
import { app } from 'https-localhost';
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.
getCerts
const createHttpsServer = require('https-localhost'); const serverInstance = createHttpsServer(); const certs = await serverInstance.getCerts();
import { getCerts } from 'https-localhost';
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.

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.

const httpsLocalhost = require("https-localhost"); const app = httpsLocalhost(); // Creates an Express app with local HTTPS const port = process.env.PORT || 4433; // Default to 443 for HTTPS, using 4433 to avoid root permissions // Create a 'public' directory and add some static files for testing // e.g., echo '<h1>Hello, HTTPS!</h1>' > public/index.html // Serve static files from a 'public' directory // Ensure 'public' directory exists in your project root for this to work app.serve(`${__dirname}/public`); // Optionally redirect HTTP traffic to HTTPS (on the same port by default) // app.redirect(); app.listen(port, () => { console.log(`HTTPS server listening on https://localhost:${port}`); console.log(`Serving static files from ${__dirname}/public`); }); // Example of creating certificates for an additional domain and using them directly async function demonstrateCustomCerts() { // Pass a domain string to the main function to generate certificates for it const customHttpsServer = httpsLocalhost("mycustomdomain.com"); try { const customCerts = await customHttpsServer.getCerts(); console.log("\nCustom certificates generated for mycustomdomain.com:"); console.log(" Certificate present:", !!customCerts.cert); console.log(" Key present:", !!customCerts.key); // You can now use customCerts with Node's native https.createServer // Example: https.createServer(customCerts, someOtherApp).listen(8443); } catch (error) { console.error("Error generating custom certificates:", error.message); } } demonstrateCustomCerts();
https-localhost --version
Debug
Known issues
gotchaThe 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.
fix
Do not deploy applications using `https-localhost` to production. Use appropriate certificate management and server configurations for live environments.
affects: >=1.0
breakingEarlier versions (prior to v4.2.0) had compatibility issues with macOS Catalina due to underlying `mkcert` versions, potentially preventing certificate generation or trust.
fix
Upgrade to `https-localhost@4.2.0` or newer to ensure compatibility with macOS Catalina and subsequent macOS versions.
affects: <4.2.0
gotchaOn 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.
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.
affects: >=1.0
gotchaThe project is explicitly 'looking for maintainers and contributors', indicating that future development, bug fixes, and long-term support might be limited or slow.
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.
affects: >=4.7.1
breakingPrior to version 4.4.2, there were known issues with the package operating correctly on Windows systems where the user's username contained spaces.
fix
Update to `https-localhost@4.4.2` or newer to resolve issues related to Windows usernames with spaces.
affects: <4.4.2
Errors
Common errors & fixes
Error: EACCES: permission denied, mkdir '/root/.local/share/mkcert'
The package attempts to create or manage certificates in system-level directories that require elevated permissions (e.g., in macOS or Linux).
fix
Run the installation or the `https-localhost` command with `sudo`, e.g., `sudo npm i -g https-localhost` or `sudo serve ~/myproj`.
NET::ERR_CERT_AUTHORITY_INVALID in browser
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.
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`.
TypeError: require(...) is not a function
Attempting to use ES module `import` syntax or destructuring when the package only exports a function via CommonJS `module.exports`.
fix
Always use `const createServer = require('https-localhost');` or `const app = require('https-localhost')();` with CommonJS `require()` syntax.
Error: ENOENT: no such file or directory, stat '/path/to/nonexistent/public'
The path provided to `app.serve()` for static files does not exist on the filesystem.
fix
Verify that the directory specified in `app.serve(path)` exists relative to your application's entry point, or provide an absolute path.
Upgrade
Version history
4.7.1latest on npm
Audit
Dependencies
nssrequiredRequired on MacOS and Linux for Firefox and Chrome to trust locally generated certificates. It's a system-level dependency.
libnss3-toolsrequiredAlternative to 'nss' on Linux distributions for Firefox and Chrome certificate trust. It's a system-level dependency.
Agent activity
11 hits · last 30 days
node
10
OpenAI (training)
1
Resources