fix(core): docusaurus start prints and opens an https URL when HTTPS is enabled (AI-assisted) (#12716)

The open URL protocol was only derived from the unprefixed `HTTPS=true` env
var, ignoring `--https`, `--ssl-cert`/`--ssl-key` and the `DOCUSAURUS_*` env
vars. The HTTPS config is now resolved once, and shared between the open URL
and the dev server.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: slorber

packages/docusaurus/src/commands/start/__tests__/utils.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import path from 'node:path';
+import {createOpenUrlContext} from '../utils';
+import type {StartCLIOptions} from '../start';
+
+vi.mock('../../../server/getHostPort', () => ({
+  getHostPort: async () => ({host: 'localhost', port: 3000}),
+}));
+
+describe('createOpenUrlContext', () => {
+  function getCertFixture(name: string) {
+    return path.join(
+      __dirname,
+      '../../../webpack/utils/__tests__/__fixtures__/getHttpsConfig',
+      name,
+    );
+  }
+
+  async function getOpenUrl(cliOptions: StartCLIOptions) {
+    const context = await createOpenUrlContext({cliOptions});
+    return context.getOpenUrl({baseUrl: '/baseUrl/', router: 'browser'});
+  }
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('returns an http url by default', async () => {
+    await expect(getOpenUrl({})).resolves.toBe(
+      'http://localhost:3000/baseUrl/',
+    );
+  });
+
+  it('returns an https url with --https', async () => {
+    await expect(getOpenUrl({https: true})).resolves.toBe(
+      'https://localhost:3000/baseUrl/',
+    );
+  });
+
+  it('returns an https url with --ssl-cert and --ssl-key', async () => {
+    await expect(
+      getOpenUrl({
+        sslCert: getCertFixture('host.crt'),
+        sslKey: getCertFixture('host.key'),
+      }),
+    ).resolves.toBe('https://localhost:3000/baseUrl/');
+  });
+
+  it('returns an https url with DOCUSAURUS_HTTPS=true', async () => {
+    vi.stubEnv('DOCUSAURUS_HTTPS', 'true');
+    await expect(getOpenUrl({})).resolves.toBe(
+      'https://localhost:3000/baseUrl/',
+    );
+  });
+
+  it('returns an http url with DOCUSAURUS_HTTPS=false', async () => {
+    vi.stubEnv('DOCUSAURUS_HTTPS', 'false');
+    await expect(getOpenUrl({})).resolves.toBe(
+      'http://localhost:3000/baseUrl/',
+    );
+  });
+
+  it('shares the resolved HTTPS config with the dev server', async () => {
+    const context = await createOpenUrlContext({
+      cliOptions: {
+        sslCert: getCertFixture('host.crt'),
+        sslKey: getCertFixture('host.key'),
+      },
+    });
+    expect(context.httpsConfig).toEqual({
+      cert: expect.any(Buffer),
+      key: expect.any(Buffer),
+    });
+  });
+});

packages/docusaurus/src/commands/start/utils.ts

@@ -11,6 +11,9 @@ import {normalizeUrl} from '@docusaurus/utils';
 import logger, {PerfLogger} from '@docusaurus/logger';
 import {realpath} from '@docusaurus/fs';
 import {getHostPort} from '../../server/getHostPort';
+import getHttpsConfig, {
+  type HttpsConfig,
+} from '../../webpack/utils/getHttpsConfig';
 import {
   loadSite,
   type LoadSiteParams,
@@ -44,6 +47,7 @@ function getOpenUrlOrigin(
 export type OpenUrlContext = {
   host: string;
   port: number;
+  httpsConfig: HttpsConfig;
   getOpenUrl: ({
     baseUrl,
     router,
@@ -53,12 +57,17 @@ export type OpenUrlContext = {
   }) => string;
 };
 
-async function createOpenUrlContext({
+export async function createOpenUrlContext({
   cliOptions,
 }: {
   cliOptions: StartCLIOptions;
 }): Promise<OpenUrlContext> {
-  const protocol: string = process.env.HTTPS === 'true' ? 'https' : 'http';
+  const httpsConfig = await getHttpsConfig({
+    https: cliOptions.https,
+    sslCert: cliOptions.sslCert,
+    sslKey: cliOptions.sslKey,
+  });
+  const protocol = httpsConfig ? 'https' : 'http';
 
   const {host, port} = await getHostPort(cliOptions);
   if (port === null) {
@@ -73,7 +82,7 @@ async function createOpenUrlContext({
     ]);
   };
 
-  return {host, port, getOpenUrl};
+  return {host, port, httpsConfig, getOpenUrl};
 }
 
 type StartParams = {

packages/docusaurus/src/commands/start/webpack.ts

@@ -14,7 +14,6 @@ import {
 } from '@docusaurus/bundler';
 import logger from '@docusaurus/logger';
 import {createPollingOptions} from './watcher';
-import getHttpsConfig from '../../webpack/utils/getHttpsConfig';
 import {
   createConfigureWebpackUtils,
   executePluginsConfigureWebpack,
@@ -32,6 +31,7 @@ import type {Configuration as DevServerConfig} from 'webpack-dev-server';
 import type {Compiler as RspackCompiler} from '@rspack/core';
 import type {Configuration as RspackDevServerConfig} from '@rspack/dev-server';
 import type {OpenUrlContext} from './utils';
+import type {HttpsConfig} from '../../webpack/utils/getHttpsConfig';
 
 // E2E_TEST=true docusaurus start
 // Makes "docusaurus start" exit immediately on success/error, for E2E test
@@ -54,27 +54,23 @@ function registerWebpackE2ETestHook(compiler: Compiler) {
   });
 }
 
-async function createDevServerConfig({
+function createDevServerConfig({
   cliOptions,
   props,
   host,
   port,
+  httpsConfig,
 }: {
   cliOptions: StartCLIOptions;
   props: Props;
   host: string;
   port: number;
-}): Promise<DevServerConfig> {
+  httpsConfig: HttpsConfig;
+}): DevServerConfig {
   const {baseUrl, siteDir, siteConfig} = props;
 
   const pollingOptions = createPollingOptions(cliOptions);
 
-  const httpsConfig = await getHttpsConfig({
-    https: cliOptions.https,
-    sslCert: cliOptions.sslCert,
-    sslKey: cliOptions.sslKey,
-  });
-
   // https://webpack.js.org/configuration/dev-server
   return {
     hot: cliOptions.hotOnly ? 'only' : true,
@@ -178,11 +174,12 @@ export async function createWebpackDevServer({
   const compiler = props.currentBundler.instance(config);
   registerWebpackE2ETestHook(compiler);
 
-  const defaultDevServerConfig: DevServerConfig = await createDevServerConfig({
+  const defaultDevServerConfig: DevServerConfig = createDevServerConfig({
     cliOptions,
     props,
     host: openUrlContext.host,
     port: openUrlContext.port,
+    httpsConfig: openUrlContext.httpsConfig,
   });
 
   // Allow plugin authors to customize/override devServer config

packages/docusaurus/src/webpack/utils/getHttpsConfig.ts

@@ -156,12 +156,14 @@ You only provided a ${cert ? 'certificate' : 'key'} (with ${fileProvided.source}
   }
 }
 
+export type HttpsConfig = boolean | {cert: Buffer; key: Buffer};
+
 // Get the https config
 // Return cert files if provided via CLI or env, otherwise just true or false.
 // CLI options take precedence over env vars.
 export default async function getHttpsConfig(
   options: Partial<HttpsConfigOptions> = {},
-): Promise<boolean | {cert: Buffer; key: Buffer}> {
+): Promise<HttpsConfig> {
   const cwd = await realpath(process.cwd());
 
   const [cert, key] = await Promise.all([