Creating HTTPS Environment for React Development: Using mkcert Tool
Author: Tim Connolley
19 July, 2024
When developing a Single Page Application (SPA) such as a React app that involves authentication or secure communication, it often becomes necessary to run the development environment over HTTPS. This requirement can stem from using an authentication provider that mandates HTTPS for security reasons. Setting up SSL certificates for local hosts is crucial for mirroring the production environment as closely as possible and avoiding security warnings during development. This guide provides step-by-step instructions on how to set up SSL certificates locally using the `mkcert` tool.
Why SSL on Localhost?
Using SSL (HTTPS) on localhost ensures that:
- Your app can consume secure services and APIs that require HTTPS.
- You comply with OAuth and other authentication mechanisms that may reject non-HTTPS callbacks.
- You develop and test features that require secure contexts, like geolocation, in a more production-like environment.
What is `mkcert`?
[`mkcert`](https://www.npmjs.com/package/mkcert) is a simple tool for making locally trusted development certificates. It requires zero configuration and works seamlessly out of the box. Unlike self-signed certificates, certificates created by `mkcert` are automatically trusted by your system’s certificate store, meaning you don’t get those annoying browser warnings.
Step-by-Step Guide
1- Install `mkcert`
To begin, you need to install `mkcert` globally via npm:
```bash
npm install -g mkcert
``` 2- Decide Where to Save Your Certs
First, decide on where you would like to save your certs. It can be your project folder or a common folder accessible to all your projects on your system. This could be something like `c:/dev/.cert` on Windows or `~/dev/.cert` on macOS/Linux. I chose a common folder, so I didn’t have to create a CA for every project.
Create the directory if it does not exist, then navigate to it.
```bash
mkdir <full-path-to-directory>/<directory-name>
cd <full-path-to-directory>/<directory-name>
```
```bash
mkdir c:/dev/.cert
cd c:/dev/.cert
``` 3- Create a Certificate Authority (CA)
A Certificate Authority (CA) acts as a trusted entity that issues digital certificates. By creating your own CA with `mkcert`, you can sign your local certificates such that they are trusted by your operating system and browsers.
Create your CA with the following command:
```bash
mkcert create-ca --validity 900 --key [name].key --cert [name].crt
```
```bash
mkcert create-ca --validity 900 --key ca.key --cert ca.crt
``` I chose to name my files `ca.key` and `ca.cert`.
Note: The `validity` parameter sets the duration that the certificate is considered valid. Here, `900` days is just an example; adjust it based on your preference.
4- Create a Localhost Certificate
With the CA created, you can now generate an SSL certificate for `localhost`:
```bash
mkcert create-cert --validity 900 --ca-key [ca-name].key --ca-cert [ca-name].crt--key [cert-name].key --cert [cert-name].crt --domain localhost
```
```bash
mkcert create-cert --validity 900 --ca-key ca.key --ca-cert ca.crt --key cert.key --cert cert.crt --domain localhost
``` Ensure that `[ca-name]` points to the `.key` and `.crt` files you generated in the previous step.
5- Trust the Certificate
On Windows:
- Navigate to your certificate directory (my example: `c:/dev/.cert`) in your file explorer.
- Double-click each `.crt` file to open the certificate installation dialog.
- Choose “Install Certificate”.
- Select whether to store it for the current user or the local machine (admin rights required for the latter).
- Place all certificates in the “Trusted Root Certification Authorities” store.
On macOS:
- Open the Keychain Access tool.
- Import your `.crt` files to the “System” keychain.
- Set the trust settings to “Always Trust”.
6- Configure Your Development Environment
In your SPA project, such as a React app, configure the development server to use your SSL certificates. For instance, if you’re using `create-react-app`, you can set environment variables in your `.env` file:
```plaintext
SSL_CRT_FILE=<full-path-to-cert.crt>
SSL_KEY_FILE=<full-path-to-cert.key>
``` Replace `<full-path-to-cert.crt>` and `<full-path-to-cert.key>` with the absolute paths to your certificate files.
Conclusion
By following these steps, you’ve set up a secure, HTTPS-enabled development environment for your SPA. This setup not only improves security but also ensures compatibility with modern web APIs and authentication services that require HTTPS. Happy secure coding!
Read more on related topics:
