Setting Up Local SSL Certificates for Local Development of a React App

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: 

1. Simplify Android and iOS App Development with Cross-Platform Frameworks 
2. 10 Best Software Development Methodologies 
3. Emerging Trends in Software Development