Provision local HTTPS certificates automatically when running Vite with `localHttps` by fredericoo · Pull Request #3953 · Shopify/hydrogen

fredericoo · 2026-08-14T13:21:31Z

TL;DR: Local HTTPS for Vite-based setups required a manual, macOS-specific mkcert setup before Customer Account flows worked. This PR (stacked on #3936) makes provisioning portable across macOS, Linux, and Windows while keeping the system trust change explicit and reversible.

Before

brew install mkcert
mkcert -install
mkdir -p ~/.shopify/hydrogen/certs
mkcert -cert-file ~/.shopify/hydrogen/certs/local.tryhydrogen.dev.pem \
  -key-file ~/.shopify/hydrogen/certs/local.tryhydrogen.dev-key.pem local.tryhydrogen.dev

After

vite dev                                # asks before provisioning missing certificates
npx hydrogen certs install              # provision explicitly
npx hydrogen certs uninstall            # remove Hydrogen's certificate files
npx hydrogen certs uninstall --remove-ca # also remove mkcert's shared CA

What this changes

localHttps() detects missing certificates during vite dev and explains that Hydrogen will download mkcert, modify the system trust store, and create a certificate before asking for confirmation. Declining or running non-interactively leaves HTTPS disabled and prints the explicit installation command.
Downloads a pinned mkcert v1.4.4 binary for macOS, Linux, or Windows on x64/arm64, verifies the platform-specific SHA-256 checksum before execution, and caches it under ~/.shopify/hydrogen/mkcert/.
Adds paired hydrogen certs install and hydrogen certs uninstall commands. Uninstall removes Hydrogen's certificate, key, and cached mkcert binary by default. --remove-ca additionally warns and runs mkcert -uninstall because that CA may be shared with unrelated projects.
Adds provisionLocalHttps() for frameworks that need certificate paths before the Vite plugin runs, including Nuxt and SolidStart.
Keeps build, preview, and CI free of automatic provisioning. Failures degrade to the existing warning with the failure reason, explicit CLI command, and manual mkcert steps.
Makes the root https:setup script cross-platform and updates the packaged local HTTPS skill and repository guidance.

Developer impact

Extends the existing minor changeset for @shopify/hydrogen. It adds the provisionLocalHttps() / ProvisionLocalHttpsOptions exports under @shopify/hydrogen/vite and the paired certificate CLI commands. Existing localHttps() call sites need no changes.

Risk

Accepting the first-run prompt or running hydrogen certs install installs mkcert's local CA into system trust stores and may prompt for a password.
mkcert uses one shared CA by default. certs uninstall therefore leaves it trusted; removing it requires the explicit --remove-ca flag and can make certificates from other projects untrusted.
mkcert v1.4.4 is pinned to six platform checksums. Updating mkcert requires updating the version and every checksum.

How to Test

Move any existing Hydrogen certificate state aside: mv ~/.shopify/hydrogen ~/.shopify/hydrogen.bak.
Run pnpm install && pnpm build:pkgs.
Run pnpm --filter @shopify/hydrogen-example-astro https:dev.
Decline the prompt and confirm no certificate is installed and the warning points to npx hydrogen certs install.
Start the command again, accept the prompt, and confirm the app serves on https://local.tryhydrogen.dev:5173 with a trusted certificate.
Run node packages/hydrogen/bin/hydrogen.mjs certs uninstall and confirm the Hydrogen certificate files are removed while the output says the shared CA remains trusted.
Restore the backup if you made one: rm -rf ~/.shopify/hydrogen && mv ~/.shopify/hydrogen.bak ~/.shopify/hydrogen.

frandiox

Nice. I had seen other Vite plugins doing something similar but since we have a core feature like customer accounts, it makes sense we export one 🤔

I'm seeing this but I think it was fixed already in MiniOxygen?

Request must contain a host header.
    at toWeb (file:///...hydrogen/node_modules/.pnpm/@shopify+mini-oxygen@4.2.0_vite@8.0.10_@types+node@22.19.17_esbuild@0.28.1_jiti@2.6.1_t_33b61828dcbe09e87499152c791ecdbb/node_modules/@shopify/mini-oxygen/dist/vite/utils.js:13:11)

frandiox · 2026-08-17T10:29:23Z

+  try {
+    await provisionCertificates(settings);


This is a big side effect when running the Vite plugin, and I'm not sure users would notice (it modifies their system to add a certificate).

Would it make sense if we use node:readline/promises or similar to block the process until the user accepts a terminal prompt? (or exit with a nice message otherwise)

That or require a manual setup https command?

Not sure really 🤔

i designed the API to support a setup step separately (useful for CI, as we skip interactive prompts)

but the DX obsessive in me wants to make it just work

the experience is pretty clear, there are logs all throughout the process, users know what's going on, so i'd say keep it?

we can add jsdoc to the httpOnly plugin saying that by using this in vite, if enabled it will create a certificate on your machine

or a prompt to get acceptance first

open to either way

I love the "it just works" but at the same time, this is modifying the system to install a certificate... I feel this is something we should ask confirmation for. Or at least have more than 1 single step to run it: force them to enable it manually and read a comment on top of it, etc.

Alternatively... is there a command we could print to uninstall the cert we just added? Perhaps that would be good enough if someone can just undo, and give them the command when they run dev:https?
It seems there's mkcert -uninstall, and we could wire it up with extra cleaning via npx hydrogen setup https --uninstall or similar? We might need a different CAROOT for mkcert so that it doesn't uninstall different certs though 🤔

very interesting

i think i will do both: one confirmation dialog following the "no magic" principle we've been following, and also a way to uninstall, probably npx hydrogen certs uninstall alongside npx hydrogen certs install which just runs the script to install them

yep, agreed - did both.

vite dev now explains the mkcert download, system trust-store change, and certificate creation before asking for confirmation. Declining makes no system changes and points to the explicit install command.

The commands are now:

npx hydrogen certs install

npx hydrogen certs uninstall removes Hydrogen's certificate files and cached binary, but leaves mkcert's shared CA trusted

npx hydrogen certs uninstall --remove-ca warns about other projects and then uninstalls the exact binary we installed before, not the user's main mkcert
I kept mkcert's default CAROOT so we reuse an existing mkcert CA rather than installing another root. Removing that shared CA therefore requires the explicit flag.

fredericoo · 2026-08-17T17:36:12Z

Nice. I had seen other Vite plugins doing something similar but since we have a core feature like customer accounts, it makes sense we export one 🤔

I'm seeing this but I think it was fixed already in MiniOxygen?
Request must contain a host header.
    at toWeb (file:///...hydrogen/node_modules/.pnpm/@shopify+mini-oxygen@4.2.0_vite@8.0.10_@types+node@22.19.17_esbuild@0.28.1_jiti@2.6.1_t_33b61828dcbe09e87499152c791ecdbb/node_modules/@shopify/mini-oxygen/dist/vite/utils.js:13:11)

yeah i fixed it but it's not released yet

edit: now fixed in preview, using the correct minioxygen version

Assisted-By: devx/07abca81-b031-4579-88c8-bc07dfd3c5aa

Assisted-By: devx/05def498-8bdd-48d0-bd5e-35e4667a2f3d

frandiox

Works great, thanks!

fredericoo changed the title ~~Provision local HTTPS certificates automatically with a pinned mkcert~~ Provision local HTTPS certificates automatically when running Vite with localHttps Aug 14, 2026

fredericoo marked this pull request as ready for review August 14, 2026 15:00

fredericoo requested a review from a team as a code owner August 14, 2026 15:00

fredericoo self-assigned this Aug 14, 2026

fredericoo added preview gsd:50917 New Hydrogen labels Aug 14, 2026

frandiox reviewed Aug 17, 2026

View reviewed changes

This was referenced Aug 17, 2026

CI: verify local HTTPS stack across operating systems #3954

Closed

Configure Customer Account URLs during local HTTPS development #3955

Open

fredericoo marked this pull request as draft August 17, 2026 18:12

fredericoo force-pushed the fb-local-https-vite-plugin-mkcert branch from a5581ff to c9897c6 Compare August 17, 2026 18:21

Base automatically changed from fb-local-https-vite-plugin to preview August 18, 2026 12:50

fredericoo added 4 commits August 19, 2026 17:08

Provision local HTTPS certificates automatically with a pinned mkcert

45ee3a4

Assisted-By: devx/07abca81-b031-4579-88c8-bc07dfd3c5aa

Replace verbose mkcert output with minimal step confirmations

743b945

Assisted-By: devx/07abca81-b031-4579-88c8-bc07dfd3c5aa

Name the operation and URL when the mkcert download times out

9b14554

Assisted-By: devx/07abca81-b031-4579-88c8-bc07dfd3c5aa

Preserve local HTTPS fallback after API refactor

b5b5d11

Assisted-By: devx/05def498-8bdd-48d0-bd5e-35e4667a2f3d

fredericoo force-pushed the fb-local-https-vite-plugin-mkcert branch from c9897c6 to b5b5d11 Compare August 19, 2026 16:17

fredericoo marked this pull request as ready for review August 19, 2026 16:22

fredericoo requested review from andguy95, frandiox and kdaviduik August 19, 2026 16:22

fredericoo added 3 commits August 20, 2026 11:55

Confirm automatic local certificate installation

aefc4d4

Add local certificate install command

e06ea6d

Add local certificate uninstall command

e060d8b

fredericoo marked this pull request as draft August 20, 2026 11:03

fredericoo added 2 commits August 20, 2026 12:07

Only remove Hydrogen's pinned mkcert binary

9b22c8e

Default local HTTPS confirmation to yes

b6a50f7

fredericoo marked this pull request as ready for review August 20, 2026 11:18

frandiox approved these changes Aug 21, 2026

View reviewed changes

fredericoo merged commit a75aba8 into preview Aug 21, 2026
5 checks passed

fredericoo deleted the fb-local-https-vite-plugin-mkcert branch August 21, 2026 10:28

Navigation Menu

Uh oh!

Provision local HTTPS certificates automatically when running Vite with `localHttps` - #3953

Provision local HTTPS certificates automatically when running Vite with `localHttps`#3953
fredericoo merged 9 commits into
previewfrom
fb-local-https-vite-plugin-mkcert

fredericoo commented Aug 14, 2026 •

edited

Loading

Uh oh!

frandiox left a comment

Uh oh!

frandiox Aug 17, 2026

Uh oh!

fredericoo Aug 17, 2026

Uh oh!

frandiox Aug 20, 2026

Uh oh!

fredericoo Aug 20, 2026

Uh oh!

fredericoo Aug 20, 2026 •

edited

Loading

Uh oh!

fredericoo commented Aug 17, 2026 •

edited

Loading

Uh oh!

frandiox left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

fredericoo commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Before

After

What this changes

Developer impact

Risk

How to Test

Uh oh!

frandiox left a comment

Choose a reason for hiding this comment

Uh oh!

frandiox Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

fredericoo Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

frandiox Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

fredericoo Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

fredericoo Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fredericoo commented Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

frandiox left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fredericoo commented Aug 14, 2026 •

edited

Loading

fredericoo Aug 20, 2026 •

edited

Loading

fredericoo commented Aug 17, 2026 •

edited

Loading