trustlocal

One command. HTTPS everywhere. Zero config.

trustlocal automates local HTTPS for web development. It uses mkcert under the hood — installing it automatically if needed, generating browser-trusted certificates, and injecting the correct SSL config into your framework. Zero manual steps.

npx trustlocal init

That's it.

The problem it solves

mkcert (58k ⭐) generates locally trusted certificates — but it stops there. You still have to:

• Wire cert files into your framework config manually
• Set NODE_EXTRA_CA_CERTS so Node trusts them
• Redo all of this for every teammate

trustlocal automates the entire chain: install → generate → inject → sync.

Supported frameworks

| Framework | Detected by | What gets configured | |---|---|---| | Next.js | next in package.json | next.config.js/ts — experimental.https block (or CLI flags for v15+) | | Vite | vite in package.json | vite.config.js/ts — server.https block | | Astro | astro in package.json | astro.config.mjs — server.https block | | SvelteKit | @sveltejs/kit in package.json | vite.config.ts — server.https block | | Nuxt | nuxt in package.json | nuxt.config.ts — devServer.https block | | Remix | @remix-run/dev in package.json | vite.config.ts — server.https block | | Fastify | fastify in package.json | .env — NODE_EXTRA_CA_CERTS + server snippet printed | | NestJS | @nestjs/core in package.json | .env — NODE_EXTRA_CA_CERTS + main.ts snippet printed | | Express / Node | express in deps or server.js present | .env — NODE_EXTRA_CA_CERTS + code snippet printed | | Nginx | nginx.conf in project root | nginx.conf — ssl_certificate directives injected | | Plain | fallback | Certs placed in .trustlocal/, manual wiring instructions printed |

Commands

init — first-time setup

npx trustlocal init

Installs mkcert if missing (no manual steps required), registers the local CA, detects your framework, generates trusted certificates, injects HTTPS config, and writes trustlocal.json so teammates can sync with one command.

Options

| Flag | Description | |---|---| | --domains <list> | Extra comma-separated domains to include, e.g. --domains myapp.local,api.local | | --force | Re-initialise even if trustlocal.json already exists | | --dry-run | Preview what would happen without writing any files |

sync — onboard a teammate

npx trustlocal sync

New developer clones the repo, runs this, and has HTTPS working in under 30 seconds. Reads trustlocal.json, generates fresh certificates on their machine (no private key sharing), and re-injects config identically.

renew — renew expiring certs

npx trustlocal renew

Certificates expire after 2 years. Deletes old certs and generates fresh ones. Framework config files are not touched — cert file paths stay the same.

| Flag | Description | |---|---| | --force | Renew even if the cert has more than 30 days remaining |

status — check your setup

npx trustlocal status

Prints a coloured OK / WARNING / ERROR for each check:

• Certificate file present and expiry date
• HTTPS config injection still in place
• NODE_EXTRA_CA_CERTS set in .env
• .trustlocal/ excluded from .gitignore

doctor — diagnose issues

npx trustlocal doctor

10-point diagnostic that checks every component of your HTTPS setup and suggests a specific fix for each problem found. Run this if something isn't working.

remove — clean uninstall

npx trustlocal remove

Removes everything trustlocal added: deletes the cert directory, strips HTTPS config from framework files, removes NODE_EXTRA_CA_CERTS from .env, cleans .gitignore, and deletes trustlocal.json.

| Flag | Description | |---|---| | --yes | Skip the confirmation prompt |

mkcert auto-install

If mkcert is not on your machine, trustlocal installs it automatically — no manual steps, no package manager required.

| Platform | Install method | |---|---| | macOS | Homebrew → direct download fallback | | Linux | apt → direct download fallback | | Windows | winget → choco → scoop → direct download fallback |

The direct download fallback fetches the official binary from GitHub releases using Node's built-in https module. No curl, no wget needed.

Security

• .trustlocal/ is automatically added to .gitignore before any cert files are written — private keys are never committed
• trustlocal.json is safe to commit — it contains no keys, only config metadata (framework, domains, cert dir)
• All certificate generation happens locally via mkcert. trustlocal never reads, stores, or transmits any private key

Requirements

• Node.js 18+
• macOS, Linux, or Windows

License

MIT © Sahil Kashyap