Skip to main content

Local HTTPS

The local HTTPS functions serve your Vite dev server on a trusted HTTPS origin that customer account login accepts. Use these functions to provision local certificates and to sync your development URLs to the Customer Account API settings.

Import localHttps, provisionLocalHttps, and LOCAL_HTTPS_DEFAULTS from @shopify/hydrogen/vite.

Anchor to Vite pluginVite plugin

Anchor to localHttps
localHttps(
options
)

Serves your Vite dev server over trusted HTTPS on a fixed host and port, and adds the dev server URLs to your Customer Account API settings. Vite exits when another process uses the port. The dev server speaks HTTP/1.1 only.

When vite dev starts without certificate files, the plugin asks for permission in the terminal, then creates the files. The plugin skips the prompt without an interactive terminal and in CI. Hydrogen treats any CI environment variable value other than an empty string, false, or 0 as CI. While certificate files are missing, the plugin prints a warning and leaves HTTPS off.

After the dev server starts, the plugin runs Shopify CLI to update your Customer Account API settings with the dev server URLs. The update needs a Shopify CLI that includes @shopify/cli-hydrogen 13.0.4 or later. When the project has no linked Hydrogen storefront, Shopify CLI asks you to link one first. When Shopify CLI is missing or outdated, or the update fails, the plugin prints the URLs to enter by hand and the dev server keeps running. In CI, the plugin prints the URLs and skips Shopify CLI.

Anchor to localHttps-parametersParameters

Anchor to options
options
required

Switch, host, port, and certificate paths for local HTTPS.

Anchor to localHttps-returnsReturns

A Vite plugin. Its api.getDevServerConfig() method returns the HTTPS settings for frameworks that serve HTTPS outside Vite.

Examples

TypeScript

import { localHttps } from "@shopify/hydrogen/vite";
import { defineConfig } from "vite";

export default defineConfig({
plugins: [
localHttps({
enabled: process.env.npm_lifecycle_event === "dev:https",
}),
],
});

Anchor to Certificate provisioningCertificate provisioning

Anchor to provisionLocalHttps
provisionLocalHttps(
options
)

Creates trusted certificate files for local HTTPS. Call the function from a setup script, or before you start a framework that reads certificate paths when its config loads, such as Nuxt.

When both files exist, the function returns their paths and changes nothing. Otherwise, the function downloads a pinned, checksum-verified mkcert release, adds the mkcert certificate authority to your system trust store, and creates the certificate and private key. mkcert can ask for your password.

Anchor to provisionLocalHttps-parametersParameters

Anchor to options
options
Default: {}

Host and certificate paths. Each option has a Hydrogen default.

Examples

TypeScript

import { provisionLocalHttps } from "@shopify/hydrogen/vite";

const { host, certPath, keyPath } = await provisionLocalHttps();

console.log(`Local HTTPS is ready for https://${host}`);
console.log(` Certificate: ${certPath}`);
console.log(` Private key: ${keyPath}`);

Anchor to Development workflowDevelopment workflow

  • Enable the plugin in a dedicated dev:https script, and keep vite dev on HTTP for work that doesn't need customer account login.
  • Next.js apps don't use the plugin. Start Next.js with next dev --experimental-https --hostname local.tryhydrogen.dev --port 5173, and configure the Customer Account API URLs in the Shopify admin by hand.
  • Astro sets the dev server host and port itself. Pass the host and port from LOCAL_HTTPS_DEFAULTS to Astro's server option.
  • Nuxt and SolidStart read certificate paths when the config loads. Run npx hydrogen certs install before the first start, or restart once after the plugin provisions certificates.
Was this page helpful?