HTTPS Server for Localhost

Common errors

• Error: EACCES: permission denied, mkdir '/root/.local/share/mkcert'

  cause 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

  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.
  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

  cause 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'

  cause 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.

Warnings

• gotcha 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.
  Fix: Do not deploy applications using `https-localhost` to production. Use appropriate certificate management and server configurations for live environments.
• breaking Earlier 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.
• gotcha 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.
  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.
• gotcha The 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.
• breaking 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.
  Fix: Update to `https-localhost@4.4.2` or newer to resolve issues related to Windows usernames with spaces.

Install

• npm install https-localhost npm
• yarn add https-localhost yarn
• pnpm add https-localhost pnpm

Imports

• default export (function)
  wrong:

  import createHttpsServer from 'https-localhost';

  correct:

  const createHttpsServer = require('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
  wrong:

  import { app } from 'https-localhost';

  correct:

  const app = require('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
  wrong:

  import { getCerts } from 'https-localhost';

  correct:

  const createHttpsServer = require('https-localhost'); const serverInstance = createHttpsServer(); const certs = await serverInstance.getCerts();

  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.

Quickstart

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();