Use HTTPS for local development

Maud Nalpas

Most of the time, http://localhost behaves like HTTPS for development purposes. However, there are some special cases, such as custom hostnames or using secure cookies across browsers, where you need to explicitly set up your development site to behave like HTTPS to accurately represent how your site works in production. (If your production website doesn't use HTTPS, make it a priority to switch to HTTPS).

This page explains how to run your site locally with HTTPS.

For brief instructions, see mkcert quick reference.**

Run your site locally with HTTPS using mkcert (recommended)

To use HTTPS with your local development site and access https://localhost or https://mysite.example (custom hostname), you need a TLS certificate signed by an entity your device and browser trust, called a trusted certificate authority (CA). The browser checks whether your development server's certificate is signed by a trusted CA before creating an HTTPS connection.

We recommend using mkcert, a cross-platform CA, to create and sign your certificate. For other helpful options, see Run your site locally with HTTPS: other options.

Many operating systems include libraries for creating certificates, such as openssl. However, they're more complex and less reliable than mkcert, and aren't necessarily cross-platform, which makes them less accessible to larger developer teams.

Setup

1. Install mkcert (only once).

   Follow the instructions for installing mkcert on your operating system. For example, on macOS:

   brew install mkcert
   brew install nss # if you use Firefox
   

2. Add mkcert to your local root CAs.

   In your terminal, run the following command:

   mkcert -install
   

   This generates a local certificate authority (CA). Your mkcert-generated local CA is only trusted locally, on your device.

3. Generate a certificate for your site, signed by mkcert.

   In your terminal, navigate to your site's root directory or whichever directory you'd like to keep your certificate in.

   Then, run:

   mkcert localhost
   

   If you're using a custom hostname like mysite.example, run:

   mkcert mysite.example
   

   This command does two things:

   • Generates a certificate for the hostname you've specified.
   • Lets mkcert sign the certificate.

   Your certificate is now ready and signed by a certificate authority your browser trusts locally.

4. Configure your server to use HTTPS the TLS certificate you've just created.

   The details of how to do this depend on your server. A few examples follow:

   👩🏻‍💻 With node:

   server.js (replace {PATH/TO/CERTIFICATE...} and {PORT}):

   const https = require('https');
   const fs = require('fs');
   const options = {
     key: fs.readFileSync('{PATH/TO/CERTIFICATE-KEY-FILENAME}.pem'),
     cert: fs.readFileSync('{PATH/TO/CERTIFICATE-FILENAME}.pem'),
   };
   https
     .createServer(options, function (req, res) {
       // server code
     })
     .listen({PORT});
   

   👩🏻‍💻 With http-server:

   Start your server as follows (replace {PATH/TO/CERTIFICATE...}):

   http-server -S -C {PATH/TO/CERTIFICATE-FILENAME}.pem -K {PATH/TO/CERTIFICATE-KEY-FILENAME}.pem
   

   -S runs your server with HTTPS, while -C sets the certificate and -K sets the key.

   👩🏻‍💻 With a React development server:

   Edit your package.json as follows, and replace {PATH/TO/CERTIFICATE...}:

   "scripts": {
   "start": "HTTPS=true SSL_CRT_FILE={PATH/TO/CERTIFICATE-FILENAME}.pem SSL_KEY_FILE={PATH/TO/CERTIFICATE-KEY-FILENAME}.pem react-scripts start"
   

   For example, if you've created a certificate for localhost in your site's root directory:

   |-- my-react-app
       |-- package.json
       |-- localhost.pem
       |-- localhost-key.pem
       |--...
   

   Then your start script should look like this:

   "scripts": {
       "start": "HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem react-scripts start"
   

   👩🏻‍💻 Other examples:

   • Angular development server
   • Python

5. Open https://localhost or https://mysite.example in your browser to double-check that you're running your site locally with HTTPS. You won't see any browser warnings, because your browser trusts mkcert as a local certificate authority.

mkcert quick reference