mk-https

Zero to https://myapp.local in one command. Wraps mkcert to generate trusted local certificates, manage /etc/hosts entries, and print framework config snippets for Next.js, Vite, Express, and Angular.

Requirements

• Node.js 20 LTS or later
• mkcert (installed automatically if missing via brew, snap, apt-get, choco, or scoop)
• macOS, Linux, or Windows

Installation

npm install -g mk-https
# or
npx mk-https init

Commands

mk-https init

Set up HTTPS for the current project from scratch.

• Prompts for domain(s) if no config file exists yet (or pass --domain to skip the prompt)
• Auto-detects your framework (Next.js, Vite, Angular, Express) from config files and package.json
• Installs mkcert if it is not already present
• Installs the local CA if not yet trusted
• Generates cert.pem and key.pem into .mk-https/
• Adds entries to /etc/hosts (requires elevated privileges — will prompt for sudo)
• Appends .mk-https/ to .gitignore
• Writes .mk-https/mk-https.json
• Prints a config snippet for your framework

mk-https init

# Non-interactive (for CI/scripts):
mk-https init --domain myapp.local --domain api.myapp.local

mk-https add <domain>

Add an additional domain to the existing HTTPS setup.

• Validates the domain format (must end in .local, .test, .localhost, or .internal)
• Regenerates the certificate to cover all domains
• Adds the new entry to /etc/hosts
• Updates mk-https.json

mk-https add api.myapp.local

mk-https remove <domain>

Remove a domain from the HTTPS setup.

• Regenerates the certificate without the removed domain
• Removes the entry from /etc/hosts
• Updates mk-https.json

mk-https remove api.myapp.local

mk-https status

Show the current state of the HTTPS setup for this project.

• Lists configured domains
• Reports certificate expiry date (warns if expiring within 30 days)
• Checks local CA trust
• Checks /etc/hosts entries

mk-https status

mk-https renew

Regenerate the certificate for existing domains without touching /etc/hosts.

mk-https renew

mk-https clean

Remove all mk-https configuration for this project.

• Strips the marker block from /etc/hosts
• Deletes the .mk-https/ directory (certs and config)
• Strips the marker block from .gitignore
• Does not remove mkcert or the local CA — those are system-level

mk-https clean

mk-https doctor

Run a full environment health check and print a pass/fail summary for each item:

  ✔ mkcert installed
  ✔ Local CA trusted (OS cert store)
  ✘ Firefox trust (NSS certutil present) — install libnss3-tools for Firefox support
  ✔ Cert file exists
  ✔ Key file exists
  ✔ Cert covers all configured domains
  ✔ Cert validity — expires Thu Jan 01 2026 (365 days)
  ✔ /etc/hosts entries present
  ✔ mk-https.json schema version current

mk-https doctor

Framework setup

mk-https init detects your framework and prints the config snippet you need. You can also run mk-https doctor any time to check the full environment.

Next.js (≥ 13.1)

// next.config.ts
const nextConfig = {
  experimental: {
    https: {
      key: '.mk-https/key.pem',
      cert: '.mk-https/cert.pem',
    },
  },
};

export default nextConfig;

Next.js 14+ App Router note: Local HTTPS dev works with experimental.https, but some middleware and edge features may behave differently over HTTPS in development.

Vite

// vite.config.ts
import { defineConfig } from 'vite';
import fs from 'fs';

export default defineConfig({
  server: {
    https: {
      key: fs.readFileSync('.mk-https/key.pem'),
      cert: fs.readFileSync('.mk-https/cert.pem'),
    },
  },
});

Express

import https from 'https';
import { readFileSync } from 'fs';
import app from './app.js';

const server = https.createServer(
  {
    key: readFileSync('.mk-https/key.pem'),
    cert: readFileSync('.mk-https/cert.pem'),
  },
  app,
);

server.listen(443);

Angular

// angular.json — projects.<name>.architect.serve.options
{
  "ssl": true,
  "sslKey": ".mk-https/key.pem",
  "sslCert": ".mk-https/cert.pem"
}

Or via CLI:

ng serve --ssl --ssl-key .mk-https/key.pem --ssl-cert .mk-https/cert.pem

How it works

1. mkcert creates a local Certificate Authority (CA) and installs it into the OS cert store (and Chrome/Edge on macOS/Windows).
2. mk-https uses that CA to issue a certificate for your local domain(s) (.local, .test, .localhost, or .internal).
3. Entries are added to /etc/hosts so the domain resolves to 127.0.0.1 and ::1 (IPv6).
4. Your browser trusts the cert because it trusts the local CA.

Firefox

Firefox uses its own NSS cert store. mkcert -install covers this automatically if certutil is present. Install it with:

• Linux: sudo apt-get install libnss3-tools
• macOS: brew install nss

Run mk-https doctor to check if certutil is available.

Elevation / sudo

Writing to /etc/hosts requires administrator privileges. When needed, mk-https re-invokes itself with sudo (macOS/Linux) or via a UAC-elevated PowerShell process (Windows). You will see a password prompt the first time. On Linux/macOS you can also pre-authorize with sudo -v.

Project config (.mk-https/mk-https.json)

{
  "version": "1.0.0",
  "domains": ["myapp.local", "api.myapp.local"],
  "certPath": ".mk-https/cert.pem",
  "keyPath": ".mk-https/key.pem",
  "framework": "nextjs",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

The .mk-https/ directory is automatically added to .gitignore — never commit your local certs.

Notes

• mk-https never runs side effects during npm install (no postinstall scripts).
• All paths are resolved relative to the current working directory (process.cwd()).
• Framework config files are not modified — only a snippet is printed for you to copy.
• mk-https clean removes project-level HTTPS config but does not uninstall mkcert or the local CA.

License

MIT