React(vite) 로컬 개발 환경 https 적용하기

팀플 중에 로컬호스트 개발환경을 http에서 https로 바꿀 일이 생겼다.
로컬 개발 환경에서 HTTP(http://localhost)를 사용하면, 쿠키의 Secure 속성 때문에 쿠키가 전송되지 않는다.
이를 해결하려면 로컬에서도 HTTPS(https://localhost)를 적용해야 한다.

1. mkcert로 로컬 HTTPS 인증서 생성

mkcert란?

로컬 환경에서 신뢰할 수 있는 TLS/SSL 인증서를 생성하는 도구다.
이를 사용하면 브라우저에서 보안 경고 없이 HTTPS를 적용할 수 있다.

1.1 mkcert 설치

현재 프로젝트의 경로에서 실행한다.
프로젝트 폴더 안에 키가 생성되어서 간편하다.
만약 다른 경로에서 해당 과정을 실행했다면 파일들을 실제 개발하는 폴더의 루트 경로로 옮기면 된다.

//Windows (파워셀 등을 관리자 권한으로 실행)
choco install mkcert

//리눅스
brew install mkcert

1.2 로컬 CA(인증 기관) 생성 및 인증서 발급

설치 후, 인증서를 생성하기 위해 다음 명령어를 실행한다

mkcert -install

mkcert localhost or mkcert 도메인 // 현재 프로젝트에선 mkcert localhost 입력

mkcert localhost or mkcert 도메인

• 현재 개발 환경의 주소가 http://localhost:5173/ 라면, mkcert localhost를 입력하면 된다.
• IP 주소(127.0.0.1)도 함께 추가하려면 mkcert localhost 127.0.0.1를 입력하면 된다.

2. React(Vite)에서 사용

2.1 .env 파일에 환경변수 추가

VITE_DEVELOP=true

2.2 환경변수를 활용해 HTTPS 설정

import react from "@vitejs/plugin-react";
import fs from "fs";
import path from "path";
import { defineConfig, loadEnv, ConfigEnv } from "vite";

export default ({ mode }: ConfigEnv) => {
  process.env = { ...process.env, ...loadEnv(mode, process.cwd()) };

  const isDevelop: boolean = process.env.VITE_DEVELOP === 'true'; // 환경변수를 Boolean으로 변환

  return defineConfig({
    plugins: [react()],
    base: "/",
    resolve: {
      alias: {
        "@": path.resolve(__dirname, "./src"),
      },
    },
    server: {
      https: isDevelop
        ? {
            key: fs.readFileSync("localhost-key.pem"),
            cert: fs.readFileSync("localhost.pem"),
          }
        : undefined, // false 대신 undefined 사용하여 타입 에러 방지
    },
  });
};

2.3 gitignore에 추가

localhost-key.pem과 localhost.pem 파일은 개발 환경에서만 사용하는 로컬 인증서이므로, GitHub에 올리지 않는 것이 적절하다.

.gitignore

localhost.pem
localhost-key.pem

팀플의 경우
팀원들도 mkcert를 설치하고 직접 인증서를 생성하도록 안내하는 것이 가장 좋다.

문제

브랜치 이동 시 localhost-key.pem과 localhost.pem 파일이 사라진다.
파워쉘 등에서 mkcert localhost(혹은 mkcert localhost ip주소) 를 입력하여 다시 만들 수 있다.
일단 두 파일들을 따로 백업해놓고 새로운 브랜치 생성시마다 프로젝트 폴더에 넣어보자.

참고 자료

• [Next.js, React(vite.js)] 로컬 개발 환경 https 적용하기