How to configure https (SSL) locally?

A React application is in many cases scaffolded with create-react-app and if you're running it locally its served using HTTP. A production application should run in HTTPS (SSL) for security reasons, in some cases a local version has to run on https for authenticating users on the backend, when using AzureB2C, or using the proxy feature or similar. Let's see how this can be achieved.

Using HTTPS in development

Set HTTPS environment flag

This feature requires [email protected]. To enable HTTPS you have to set the environment variable to true, then start the dev server as usual with npm start.

💰 The Pragmatic Programmer: journey to mastery. 💰 One of the best books in software development, sold over 200,000 times.

When using Windows with cmd.exe:

set HTTPS=true&&npm start

When using Windows with Powershell:

($env:HTTPS = "true") -and (npm start)

Linux or macOS with Bash:

HTTPS=true npm start

If you want a more general approach on setting the environment variable, you can use a package like cross-env.

I scaffolded a React app with create-react-app ssl-test, and after running the command (linux) the output looks like this:

$ HTTPS=true npm start

> [email protected] start C:\dev\ssl-test
> react-scripts start

i ｢wds｣: Project is running at https://123.123.123.123
i ｢wds｣: webpack output is served from
i ｢wds｣: Content not from webpack is served from C:\dev\ssl-test\public
i ｢wds｣: 404s will fallback to /
Starting the development server...

Compiled successfully!

You can now view ssl-test in the browser.

  Local:            https://localhost:3000
  On Your Network:  https://123.123.123.123

Note that the development build is not optimized.
To create a production build, use yarn build.

The server will use a self-signed certificate, so your web browser will display a warning when accessing the entry point of the application.

Custom SSL certificate

You have to create a local Certificate Authority, and an SSL certificate and set the SSL_CERT_FILE and SSL_KEY_FILE to the generated files.

Generating an SSL Certificate

As the first step, you should generate a local Certificate Authority, and an SSL certificate for Local Development.

1. You need a package manager to install mkcert:
   • MacOS: Use Homebrew or Macports.
   • Linux: Use certutil. Arch Linux only, mkcert is available on the Arch Linux repository.
   • Windows: Use chocolatey.
2. Install mkcert.
3. Create a locally trusted CA with mkcert -install.
4. Generate an SSL certificate with mkcert localhost.

Set custom SSL certificate

After generating the local certificate authority and ssl certificate we have to set the SSL_CRT_FILE and SSL_KEY_FILE environment variables to the path of the certificate and key files. HTTPS has to be also true.

Windows:

set HTTPS=true&&set SSL_CRT_FILE={CERT-PATH}&&set SSL_KEY_FILE={KEY-PATH}&&react-scripts start

Linux, macOS:

HTTPS=true SSL_CRT_FILE={CERT-PATH} SSL_KEY_FILE={KEY-PATH} react-scripts start

The variables CERT-PATH and KEY-PATH are the paths to the generated files. Eventually, we set the command as the npm start script, and the application runs on HTTPS.

"scripts": {
    "start": "HTTPS=true SSL_CRT_FILE={CERT-PATH} SSL_KEY_FILE={KEY-PATH} react-scripts start"
}

TL;DR

• To enable HTTPS locally, the HTTPS environment variable needs to be set to true, local certificate authority and ssl certificate have to be created and set in the environment to avoid the unsecure warning in web browsers.

Thanks for reading and if you have any questions, use the comment function or send me a message @mariokandut. If you want to know more about React, have a look at these React Tutorials.

References (and Big thanks):

bitsrc.io - dulanka, create-react-app, chocolatey, mkcert, cross-env