vellalog

MySQL과 Tailscale로 안전한 홈서버 만들기(외부 접속)

vellahw — Fri, 31 Jul 2026 19:50:23 +0900

기존에 오라클로 홈서버를 만들었었다. 요기

AWS로 환경을 변경하면서 MySQL로 마이그레이션을 하게 돼서 MySQL로 홈서버를 구축했다.

처음에는 오라클 환경처럼 공유기 포트포워딩으로 MySQL의 3306 포트를 외부에 공개하려 했지만

이번에는 Tailscale이란 신세계를 접하게 되어 Tailscale을 사용해 구축했다.

Tailscale을 이용하면 인터넷 상에 포트를 공개하지 않고 팀원만 안전하게 접속할 수 있다.
팀원은 내 컴퓨터의 공인 IP나 공유기 내부 IP로 접속하지 않고 Tailscale이 발급한 100.x.x.x 형태의 전용 IP로 MySQL에 접속한다.

Tailscale을 사용하면 공인 IP가 변경되어도 영향을 받지 않기 때문에 IP가 변경될 걱정을 하지 않아도 된다!

MySQL 외부 접속 허용하기

팀원이 접속하려면 MySQL이 외부 네트워크 인터페이스에서도 연결을 받도록 설정해야 한다.

C:\ProgramData\MySQL\MySQL Server 8.4\my.ini

MySQL 설정 파일은 일반적으로 위와 같은 위치에 있고 ProgramData는 숨김 폴더다.

my.ini를 관리자 권한으로 열고 [mysqld] 부분의 bind-address를 0.0.0.0으로 수정한다.

[mysqld]
bind-address=0.0.0.0
port=3306

bind-address가 127.0.0.1으로 되어있다면 다른 PC에서는 접속할 수 없고 로컬 연결만 허용한다.

설정을 수정했다면 PowerShell에 아래 명령어를 입력한다.

Restart-Service MySQL84

1. MySQL 서비스를 재시작한다.

Get-NetTCPConnection -LocalPort 3306 -State Listen

2. 정상적으로 포트를 열고있는지 확인한다.

위처럼 나오면 정상이다.

127.0.0.1:3306만 나온다면 my.ini 설정을 다시 확인해야 한다.

프로젝트 데이터베이스 생성하기

먼저 MySQL 환경변수를 등록하지 않았다면 등록해준다.

경로: C:\Program Files\MySQL\MySQL Server 8.4\bin

MySQL 관리자 계정으로 접속한다.

mysql -u root -p

비밀번호를 입력할 때 PowerShell 화면에는 아무것도 표시되지 않는다.

입력이 안 되는 것처럼 보여도 실제로는 입력되고 있으므로 비밀번호를 입력하고 Enter를 누르면 된다.

이번 프로젝트에서 사용할 데이터베이스를 생성한다.

CREATE DATABASE 프로젝트명
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_0900_ai_ci;

생성된 데이터베이스를 확인한다.

SHOW DATABASES;

외부 접속용 계정 만들기

팀원이 접속할 때 root 계정을 사용하면 안 된다.

root는 서버 전체를 관리할 수 있기 때문에 문제가 생겼을 때 피해 범위가 너무 크다.

따라서 팀원별로 별도의 계정을 만드는 것이 좋다.

CREATE USER 'gildong'@'100.90.30.40'
IDENTIFIED BY '길고-복잡한-개별비밀번호';

gildong 에는 팀원 이름이나 닉네임을, @뒤 부분엔 팀원의 IP를 입력하면 된다.

아직 팀원의 Tailscale IP를 모르는 상태라면 다음처럼 계정을 만들 수 있다.

CREATE USER 'team_user'@'%'
IDENTIFIED BY '길고-복잡한-비밀번호';

'team_user'@'%'는 모든 IP에서 해당 계정으로 로그인할 수 있다는 의미다.

팀원에게 필요한 권한을 부여한다.

GRANT SELECT, INSERT, UPDATE, DELETE,
      CREATE, ALTER, INDEX, REFERENCES
ON 데이터베이스명.*
TO 'gildong'@'100.90.30.40';

FLUSH PRIVILEGES;

개발 중 테이블 삭제가 필요하다면 DROP 권한을 추가한다.

GRANT DROP
ON 데이터베이스명.*
TO 'gildong'@'100.90.30.40';

아래 명령어를 입력해 마무리.

FLUSH PRIVILEGES;

등록된 사용자와 접속 허용 주소는 다음 쿼리로 확인한다.

SELECT User, Host
FROM mysql.user;

Tailscale 설치하기

Tailscale은 여러 컴퓨터를 하나의 사설 네트워크처럼 연결해주는 VPN 서비스다.

Tailscale 다운로드

MySQL 홈서버로 사용할 내 컴퓨터와 팀원 컴퓨터에 모두 Tailscale을 설치해 각자 계정을 만들어 로그인한다.

내 홈서버의 Tailscale IP는 다음 명령어로 확인한다.

tailscale ip -4

명령어를 입력하면 나오는 주소가 팀원이 MySQL에 접속할 때 사용할 호스트 주소다.

팀원에게 홈서버 장치 공유하기

먼저 Tailscale 관리자 페이지로 이동한다.

Tailscale Machines 관리 페이지

다음 순서로 공유한다.

1. MySQL이 설치된 홈서버 컴퓨터를 찾는다.
2. 오른쪽의 ⋯ 버튼을 hover하면 노출되는 Share를 선택
3. 팀원의 이메일을 입력하고 초대를 전송한다.
4. 팀원이 이메일로 받은 초대를 수락한다.

장치 공유 방식을 사용하면 팀원에게 내 Tailscale 네트워크 전체가 노출되지 않고 공유한 홈서버 한 대에만 접근할 수 있다.

팀원이 여러 명이라면 이메일로 각각 초대하는 것이 안전하다.

Windows 방화벽에서 MySQL 허용하기

Tailscale 연결이 되어 있어도 Windows 방화벽이 3306 포트를 막고 있으면 팀원은 MySQL에 접속할 수 없다.

팀원 컴퓨터에서 다음 명령어로 Tailscale IP를 확인한다.

tailscale ip -4

팀원 IP가 100.x.x.x 이라면 내 홈서버의 관리자 PowerShell에서 해당 IP만 허용한다.

New-NetFirewallRule `
  -DisplayName "MySQL - 팀원 홍길동" `
  -Direction Inbound `
  -Protocol TCP `
  -LocalPort 3306 `
  -RemoteAddress 100.x.x.x `
  -Action Allow

팀원이 여러 명이라면 팀원별로 규칙을 만드는 것이 관리하기 편하다.

등록된 MySQL 방화벽 규칙은 다음 명령어로 확인한다.

Get-NetFirewallRule |
  Where-Object DisplayName -Like "*MySQL*" |
  Format-Table DisplayName, Enabled, Direction, Action

팀원 컴퓨터에서 연결 테스트하기

팀원이 DBeaver를 바로 실행하기 전에 Tailscale 연결부터 확인해야 한다.

팀원 컴퓨터에서 다음 명령어를 실행한다.

tailscale status

목록에 공유받은 홈서버가 보여야 한다.

그다음 Tailscale 전용 ping을 실행한다.

tailscale ping 100.x.x.x

여기서 입력하는 IP는 반드시 내 홈서버의 Tailscale IP여야 한다.

마지막으로 MySQL 3306 포트에 연결할 수 있는지 확인한다.

Test-NetConnection 100.x.x.x -Port 3306

정상이라면 다음과 같이 표시된다.

TcpTestSucceeded : True

DBeaver에서 홈서버 MySQL 연결하기

팀원은 DBeaver에서 MySQL 연결을 추가하고 다음과 같이 설정한다.

DB 종류: MySQL
Host: 내 홈서버의 Tailscale IP
Port: 3306
Database: 데이터베이스명
Username: 팀원 전용 계정
Password: 팀원 전용 비밀번호

Test Connection을 눌러 연결을 확인한다.

Spring Boot에서는 다음과 같이 설정할 수 있다.

spring:
  datasource:
    url: jdbc:mysql://100.x.x.x:3306/데이터베이스명?serverTimezone=Asia/Seoul&characterEncoding=UTF-8
    username: gildong
    password: ${DB_PASSWORD}
    driver-class-name: com.mysql.cj.jdbc.Driver

⚠️ TcpTestSucceeded : False가 발생했을 때

팀원이 다음 명령어를 실행했는데 실패할 수 있다.

Test-NetConnection 100.x.x.x -Port 3306

TcpTestSucceeded : False

이 오류는 아직 MySQL 계정이나 비밀번호를 확인하는 단계까지 도달하지 못했다는 뜻이다. 보통 다음 중 하나가 원인이다.

잘못된 IP를 입력했다.
Tailscale 연결이 끊겨 있다.
장치 공유 초대를 수락하지 않았다.
MySQL 서비스가 중지되어 있다.
MySQL이 127.0.0.1에서만 연결을 받고 있다.
Windows 방화벽이 3306 포트를 차단하고 있다.

먼저 팀원 컴퓨터에서 확인한다.

tailscale status
tailscale ping 내_홈서버_Tailscale_IP
Test-NetConnection 내_홈서버_Tailscale_IP -Port 3306

판단 방법은 다음과 같다.

tailscale ping 실패
→ Tailscale 로그인 또는 장치 공유 문제다.

tailscale ping 성공 + 3306 실패
→ MySQL 리스닝 또는 Windows 방화벽 문제다.

3306 성공 + DBeaver 실패
→ MySQL 계정, Host, 권한 또는 비밀번호 문제다.

내 홈서버에서는 다음 항목을 확인한다.

tailscale ip -4
Get-Service -Name "MySQL*"
Get-NetTCPConnection -LocalPort 3306 -State Listen
Test-NetConnection 내_Tailscale_IP -Port 3306

LocalAddress가 127.0.0.1이라면 my.ini의 bind-address 설정을 다시 확인해야 한다.

⚠️Tailscale에서 로그아웃 또는 Expired가 뜰 때

팀원이 Tailscale에서 Logged out, Expired 또는 재인증 관련 메시지를 볼 수 있다.

Tailscale은 보안을 위해 각 장치의 인증 키를 주기적으로 만료시킨다.

인증 키가 만료되면 해당 컴퓨터는 Tailscale 네트워크에서 연결이 끊기고 MySQL에도 접속할 수 없다.

이 경우 팀원은 Tailscale 앱을 열고 다시 로그인하면 된다.

PowerShell에서는 다음 명령어로 강제 재인증할 수 있다.

tailscale up --force-reauth

브라우저가 열리면 기존에 장치 공유 초대를 수락했던 동일한 계정으로 로그인한다.

재인증 후 다음 명령어로 상태를 확인한다.

tailscale status
tailscale ip -4

그다음 다시 테스트한다.

tailscale ping 내_홈서버_Tailscale_IP
Test-NetConnection 내_홈서버_Tailscale_IP -Port 3306

재로그인 후 팀원의 Tailscale IP가 변경됐다면 Windows 방화벽과 MySQL 사용자에 등록한 기존 IP도 수정해야 한다.

내 홈서버는 항상 접속 가능해야 하므로 인증 키 만료를 비활성화할 수 있다.

1. Tailscale Machines 관리 페이지에 접속한다.
2. 홈서버 오른쪽의 ⋯ 버튼을 누른다.
3. Disable Key Expiry를 선택한다.

팀원 개인 컴퓨터는 보안을 위해 인증 만료를 유지하고, 만료됐을 때 다시 로그인하는 편이 좋다.

✅ 보안을 위해 꼭 지켜야 할 것

홈서버는 편리하지만 설정을 잘못하면 데이터베이스가 외부 공격에 노출될 수 있다.

최소한 다음 원칙은 지키는 것이 좋다.

- 공유기에서 3306 포트를 인터넷에 포트포워딩하지 않는다.
- 외부 접속에 root 계정을 사용하지 않는다.
- 팀원별로 MySQL 계정을 따로 만든다.
- 계정에는 프로젝트 DB에 필요한 권한만 부여한다.
- 팀원마다 서로 다른 비밀번호를 사용한다.
- Windows 방화벽 전체를 끄지 않는다.
- Tailscale IP 또는 Tailscale 대역에서만 3306을 허용한다.
- 프로젝트에서 빠진 팀원의 Tailscale 공유와 MySQL 계정을 제거한다.
- DB 비밀번호를 Git 저장소에 커밋하지 않는다.
- 중요한 데이터는 정기적으로 백업한다.

마무리

처음에는 MySQL 홈서버를 만들려면 공인 IP, 포트포워딩, 공유기 설정 등 복잡한 과정이 필요할 것이라고 생각했다.

하지만 Tailscale을 사용하니 공유기 설정 없이 내 컴퓨터와 팀원 컴퓨터를 하나의 사설 네트워크처럼 연결할 수 있었다.

오라클에 비해 너무나 간단하고 신기해서 신세계였다.

MySQL의 3306 포트를 인터넷 전체에 공개하지 않아도 된다는 점도 마음에 들었다.

비용 부담 없이 사이드 프로젝트용 공용 데이터베이스가 필요하다면 MySQL과 Tailscale을 조합한 홈서버도 충분히 괜찮은 선택이다. 우리는 배포를 위해 결국 AWS로 다시 이관했지만...

️ TanStack Query useMutation 사용법 정리 - 서버 데이터 변경부터 캐시 갱신까지

vellahw — Sun, 24 May 2026 18:26:21 +0900

React에서 API를 다루다 보면 데이터를 조회하는 것만큼 데이터를 생성하거나 수정하고 삭제하는 작업도 자주 발생한다.

TanStack Query에서는 데이터를 조회할 때 useQuery를 사용하고 서버의 데이터를 변경할 때 useMutation을 사용한다.

처음 useMutation을 접했을 때는 단순히 POST나 PUT 요청을 보내는 함수 정도로 생각했는데

실제로 사용해 보니 요청 상태 관리부터 성공/실패 처리, 기존 Query 캐시 갱신까지 함께 처리할 수 있어 꽤 편리하다고 느꼈다.

이번 글에서는 useMutation의 기본적인 사용법과 실제 프로젝트에서 자주 사용하는 패턴을 정리해보려고 한다.

useMutation이란?

useQuery와 useMutation의 차이를 간단하게 정리하면 다음과 같다.

useQuery → 데이터를 조회할 때 사용
useMutation → 데이터를 생성, 수정, 삭제할 때 사용

예를 들어 게시글 목록을 조회하는 API가 있다면 useQuery를 사용할 수 있다.

반대로 아래와 같은 작업에는 useMutation을 사용할 수 있다.

회원가입/로그인 요청
게시글 등록/수정/삭제
댓글 등록
좋아요 처리

즉, 서버의 상태를 변경하는 요청이라고 생각하면 이해하기 쉽다.

기본적인 useMutation 사용법

먼저 게시글을 수정하는 API가 있다고 가정해보면

const updatePost = async ({
  id,
  title,
  content,
}: {
  id: number;
  title: string;
  content: string;
}) => {
  const response = await fetch(`/posts/${id}`, {
    method: "PUT",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title,
      content,
    }),
  });

  if (!response.ok) {
    throw new Error("게시글 수정 실패");
  }

  return response.json();
};

이 API 함수를 useMutation과 연결하면 다음과 같이 사용할 수 있다.

import { useMutation } from "@tanstack/react-query";

const mutation = useMutation({
  mutationFn: updatePost,
});

여기서 가장 중요한 부분은 mutationFn이다.

mutationFn: updatePost

mutationFn에는 실제 서버 요청을 수행하는 함수를 전달한다.

mutation을 실행하는 mutate

useMutation을 선언했다고 해서 API 요청이 바로 실행되는 것은 아니다.

useQuery는 조건에 따라 자동으로 데이터를 가져오는 경우가 많지만

mutation은 일반적으로 사용자의 행동에 따라 실행해야 한다.

이때 사용하는 것이 mutate다.

mutation.mutate({
  id: 1,
  title: "수정된 제목",
  content: "수정된 내용",
});

예를 들어 버튼을 눌렀을 때 게시글을 수정하고 싶다면 다음과 같이 사용할 수 있다.

<button
  onClick={() =>
    mutation.mutate({
      id: 1,
      title: "수정된 제목",
      content: "수정된 내용",
    })
  }
>
  수정하기
</button>

mutate()에 전달한 객체는 그대로 mutationFn의 인자로 전달된다.

mutation.mutate({
  id: 1,
  title: "제목",
  content: "내용",
});

즉 위 함수를 실행하면 내부적으로 다음 함수가 호출되는 구조다.

updatePost({
  id: 1,
  title: "제목",
  content: "내용",
});

성공과 실패 처리하기

API 요청을 보냈다면 성공했을 때와 실패했을 때 각각 처리해야 하는 경우가 많다.

이때 onSuccess, onError를 사용할 수 있다.

const mutation = useMutation({
  mutationFn: updatePost,

  onSuccess: (data) => {
    console.log("수정 성공", data);
  },

  onError: (error) => {
    console.error("수정 실패", error);
  },
});

예를 들어 게시글 수정에 성공한 뒤 사용자에게 알림을 보여주거나 페이지를 이동할 수 있다.

const mutation = useMutation({
  mutationFn: updatePost,

  onSuccess: () => {
    alert("게시글이 수정되었어요.");
    navigate("/posts");
  },

  onError: () => {
    alert("게시글 수정에 실패했어요.");
  },
});

API 요청과 성공/실패에 따른 처리를 하나의 mutation 안에서 관리할 수 있다는 점이 편리하다.

mutate와 mutateAsync의 차이

mutation을 실행하는 방법은 크게 두 가지가 있다.

mutation.mutate();

또는

await mutation.mutateAsync();

mutate는 콜백 기반으로 처리할 때 사용하기 좋다.

mutation.mutate(
  {
    id: 1,
    title: "제목",
    content: "내용",
  },
  {
    onSuccess: () => {
      console.log("성공");
    },
    onError: () => {
      console.log("실패");
    },
  }
);

반면 mutateAsync는 Promise를 반환하기 때문에 async/await을 사용할 수 있다.

try {
  const result = await mutation.mutateAsync({
    id: 1,
    title: "제목",
    content: "내용",
  });

  console.log(result);
  navigate("/posts");
} catch (error) {
  console.error(error);
}

요청 이후 여러 작업을 순차적으로 처리해야 한다면 mutateAsync가 읽기 편한 경우가 많다.

그렇다고 mutateAsync가 항상 더 좋은 것은 아니다.

단순히 성공/실패 콜백만 필요한 경우라면 mutate와 onSuccess, onError 조합으로도 충분하다.

mutation의 상태값 활용하기

useMutation은 API 요청뿐만 아니라 현재 요청의 상태도 관리해준다.

대표적으로 다음과 같은 값을 사용할 수 있다.

mutation.isPending;
mutation.isSuccess;
mutation.isError;
mutation.data;
mutation.error;

예를 들어 요청 중에는 버튼을 비활성화할 수 있다.

<button
  onClick={handleUpdate}
  disabled={mutation.isPending}
>
  {mutation.isPending ? "수정 중..." : "수정하기"}
</button>

별도로 useState를 만들어서 로딩 상태를 관리하지 않고 mutation이 제공하는 상태를 활용할 수 있다는 장점이 있다.

❓ mutation 성공 후 화면의 데이터가 안 바뀌는 이유

useMutation을 처음 사용할 때 가장 헷갈릴 수 있는 부분인데,

게시글 수정 API 요청이 성공했는데 화면에는 수정 전 데이터가 그대로 표시되는 상황이 발생할 수 있다.

이유는 서버의 데이터와 TanStack Query가 가지고 있는 캐시는 별개이기 때문이다.

예를 들어 게시글을 다음 Query로 조회하고 있다고 가정한다.

useQuery({
  queryKey: ["post", id],
  queryFn: () => getPost(id),
});

그리고 mutation을 통해 게시글을 수정한다.

mutation.mutate({
  id,
  title,
  content,
});

서버의 게시글은 정상적으로 변경됐지만 기존 Query 캐시에는 수정 전 데이터가 남아 있을 수 있다.

따라서 mutation 성공 후 해당 Query가 오래된 데이터라는 것을 TanStack Query에 알려줘야 한다.

invalidateQueries로 캐시 무효화하기

이때 사용하는 것이 invalidateQueries다.

먼저 useQueryClient를 가져오고,

import {
  useMutation,
  useQueryClient,
} from "@tanstack/react-query";

const queryClient = useQueryClient();

mutation 성공 후 Query를 무효화한다.

const mutation = useMutation({
  mutationFn: updatePost,

  onSuccess: (_, variables) => {
    queryClient.invalidateQueries({
      queryKey: ["post", variables.id],
    });
  },
});

게시글 목록도 함께 변경될 가능성이 있다면 목록 Query도 무효화할 수 있다.

onSuccess: (_, variables) => {
  queryClient.invalidateQueries({
    queryKey: ["post", variables.id],
  });

  queryClient.invalidateQueries({
    queryKey: ["posts"],
  });
},

이렇게 하면 TanStack Query가 해당 캐시를 오래된 데이터로 판단하고 필요한 시점에 다시 조회할 수 있다.

결국 흐름은 다음과 같다.

사용자가 수정 버튼을 클릭
↓
mutation.mutate()를 실행
↓
서버에 PUT 요청
↓
서버 데이터가 변경됨
↓
onSuccess가 실행됨
↓
invalidateQueries()를 실행
↓
관련 Query가 갱신
↓
화면에 최신 데이터가 표시됨

이 흐름을 이해하는 것이 useMutation을 사용할 때 가장 중요하다.

Query Key를 정확하게 맞춰야 한다

invalidateQueries를 사용할 때는 Query Key도 중요하다.

조회할 때 다음과 같이 작성했다면,

useQuery({
  queryKey: ["post", id],
  queryFn: () => getPost(id),
});

mutation에서도 동일한 구조의 Query Key를 사용해야 한다.

queryClient.invalidateQueries({
  queryKey: ["post", id],
});

Query Key가 다르면 내가 원하는 Query가 제대로 갱신되지 않을 수 있다.

그래서 프로젝트가 커지면 Query Key를 별도로 관리하는 방식도 사용할 수 있다.

export const postKeys = {
  all: ["posts"] as const,

  detail: (id: number) =>
    ["post", id] as const,
};

사용할 때는 다음과 같이 작성할 수 있다.

queryClient.invalidateQueries({
  queryKey: postKeys.detail(id),
});

Query Key를 여러 컴포넌트에서 직접 작성하는 것보다 오타나 구조 불일치를 줄일 수 있다.

⚠️ API 에러는 반드시 throw 해야 한다

fetch를 사용할 때 특히 주의해야 하는 부분이

fetch는 HTTP 응답이 400이나 500이라고 해서 자동으로 Promise를 reject하지 않는다.

const response = await fetch("/posts", {
  method: "POST",
});

if (!response.ok) {
  throw new Error("요청 실패");
}

return response.json();

따라서 에러를 throw해야 TanStack Query가 해당 요청을 실패한 mutation으로 인식하고 onError를 실행할 수 있다.

onError: (error) => {
  console.error(error);
},

Axios처럼 HTTP 상태 코드에 따라 자동으로 reject되는 라이브러리를 사용하고 있었다면 이 차이 때문에 처음에는 헷갈릴 수 있다.

마무리

처음에는 useMutation을 단순히 POST나 PUT 요청을 보내기 위한 Hook으로 생각했다.

하지만 실제로는 서버 데이터 변경 요청뿐만 아니라 요청 상태와 성공/실패 처리, 기존 Query 캐시와의 연결까지 담당하는 기능이다.

핵심은 서버의 데이터를 변경한 뒤 기존 Query 캐시를 어떻게 최신 상태와 동기화할 것인가이다.

기본적인 CRUD에서는 mutationFn, onSuccess, invalidateQueries 정도만 제대로 이해해도 충분히 활용할 수 있지만

이후 조금 더 복잡한 UI를 구현하게 된다면 setQueryData를 이용한 직접적인 캐시 업데이트나 Optimistic Update까지 확장해서 사용할 수 있을 것이다.

React 로그인 인증 흐름 정리 (ProtectedRoute / PublicRoute 설계)

vellahw — Tue, 31 Mar 2026 11:08:49 +0900

리액트 프로젝트를 하다 보면 반드시 마주치는 문제가 있는데
바로 로그인 상태에 따른 라우팅 처리다.

나도 이번에 로그인 플로우를 구현하면서 로그인 인증이 성공 상태(200 코드)인데도 메인 페이지로 이동이 안 되는 상황을 겪었고 그 과정에서 로그인/비로그인 라우팅 구조를 한 번 제대로 정리하게 됐다.

문제 상황

처음엔 이런 구조였다.

/**
  * fileName : useCheckAuth
  * description : 로그인 상태 확인 후 필요 시 토큰 갱신 및 페이지 이동을 결정하는 커스텀 훅
  */
export const useCheckAuth = () => {
  const { data, isLoading, isError, refetch } = useAuthQuery(); // 로그인 상태 확인
  
  ...
  
  if (data) {
    const code = data.code; // 응답 코드
  
    if (code === 200) return { isLoading: false, navigateTo: "/home", showChildren: true };
  
    ...
  } 
  
  return { isLoading: false, navigateTo: "/login", showChildren: false }; 
  
};

/**
  * fileName : ProtectRoute
  * description : 인증이 필요한 라우트를 보호하는 컴포넌트. 로그인 인증된 사용자만 페이지 접근 허용
  */
export default function ProtectedRoute({ children }: { children: React.ReactNode; }) { 
  const { isLoading, navigateTo, showChildren } = useCheckAuth();
    
  ...
  
  if (navigateTo) return <Navigate to={navigateTo} replace />;
  
  if (showChildren) return children;
}

겉보기에는 문제 없어 보였다.
하지만 실제로는 구조적으로 충돌이 발생한다.

뭐가 문제였나?

핵심은 navigateTo와 showChildren을 동시에 쓰고 있었다.

ProtectedRoute에서 /home으로 보내는 로직 자체가 구조적으로 어색한 상태인거다.

즉, 인증 성공 시 이동도 하려고 하고 렌더링도 하려고 한다.

커스텀 훅에서 code === 200이면:

navigateTo: "/home"
showChildren: true

둘 다 true인 상태이다.

이 상태에서 실행 순서는:

navigateTo 먼저 실행됨
showChildren은 아예 렌더링 안 됨

게다가 /home에서도 ProtectedRoute를 쓰고 있으면 자기 자신으로 계속 redirect를 시도한다.

결과는 이동이 안 되는 것처럼 보이거나 무한 루프가 발생한다.

해결 방향

라우트 가드는 이동시키는 역할이 아니다

사실 이 로직은 설계가 잘못된거다.

인증에 성공했는데 왜 /home으로 이동시키나?

ProtectedRoute는 원래 리다이렉트 담당이 아니라 그 값만 보고 접근 허용이나 차단만 해야 하는 것이다.

역할 분리

인증 상태 판단	useCheckAuth
접근 허용/차단	ProtectedRoute
로그인 유저 접근 차단	PublicRoute
페이지 이동	로그인 성공 시

ProtectedRoute는 UI를 담당하고
useCheckAuth는 인증 상태를 판단한다.

올바른 구조

라우팅은 2개로 나눈다.

인증 필요 라우트 (Private)

로그인해야 접근 가능
예: /home, /mypage

비인증 전용 라우트 (Public)

로그인 상태면 접근하면 안 됨
예: /login, /signup

1. 인증 상태 커스텀 훅

export const useCheckAuth = () => {
  const { data, isLoading, isError } = useAuthQuery();

  if (isLoading) {
    return { isLoading: true, isAuthenticated: false };
  }

  if (isError) {
    return { isLoading: false, isAuthenticated: false };
  }

  // 이동시키지 말고 그냥 통과
  if (data?.code === 200) {
    return { isLoading: false, isAuthenticated: true };
  }

  return { isLoading: false, isAuthenticated: false };
};

핵심은 isAuthenticated 하나로 단순화하여 단일 책임 + 단순 로직으로 버그를 감소하는 것이다.

2. ProtectedRoute (로그인 필요 페이지 보호)

export default function ProtectedRoute({ children }) {
  const { isLoading, isAuthenticated } = useCheckAuth();

  if (isLoading) return <Loading />;

  if (!isAuthenticated) {
    return <Navigate to="/login" replace />;
  }

  return children;
}

로그인 안 했으면 차단

3. PublicRoute (로그인한 사람 막기)

export default function PublicRoute({ children }) {
  const { isLoading, isAuthenticated } = useCheckAuth();

  if (isLoading) return <Loading />;

  if (isAuthenticated) {
    return <Navigate to="/home" replace />;
  }

  return children;
}

로그인 했으면 로그인 페이지 들어가지 못하게 막기

4. Router 구성

<Routes>
  {/* 로그인 안 된 사람만 */}
  <Route
    path="/login"
    element={
      <PublicRoute>
        <Login />
      </PublicRoute>
    }
  />

  {/* 로그인 된 사람만 */}
  <Route
    path="/home"
    element={
      <ProtectedRoute>
        <Home />
      </ProtectedRoute>
    }
  />
</Routes>

5. 로그인 성공 시 이동 처리

const handleLogin = async () => {
  const res = await loginApi();

  if (res.success) {
    navigate("/home");
  }
};

여기서만 이동한다

내가 했던 실수

내가 했던 실수를 정리하자면

❌ ProtectedRoute에서 /home으로 보내기

이건 절대 하면 안 된다.

❌ navigateTo + showChildren 같이 쓰기

이 경우 상태 충돌이 발생한다.

❌ 인증 성공 시 redirect를 가드에서 처리

이 경우는 책임 분리가 깨진다.

결론

라우팅은 단순해야 버그가 없다.

인증 훅 → 상태만 반환한다
라우트 가드 → 막기만 한다
페이지 이동 → 이벤트에서 처리한다

이 3개만 지켜도 로그인 플로우는 거의 꼬이지 않을 것이다.

Oracle XE 홈서버 만들기(외부 접속)부터 SQL Developer ORA-17410 에러 해결까지

vellahw — Sat, 21 Mar 2026 02:02:44 +0900

사이드 플젝을 오라클 홈서버를 구축해 공용DB로 이용하고자 도전해봤다.

여러 블로그를 참고했는데 나는 한끝 다르게 성공... 왜 다른거지

이 글을 바탕으로 진행했다.

기본 게이트웨이 주소가 접속 안 되는걸 시작으로

분명 구축에 성공했는데 ORA-17410 에러가 뜨면서 데이터베이스 접촉 자체가 안 됐었다.

해결 방법을 순차적으로 정리해본다...

1. 포트포워딩

먼저 공유기 관리자 페이지에 접속해 포트포워딩을 해줘야한다.

포트포워딩을 해주기 위해선

cmd에 ipconfg 를 입력해 내 IPv4 주소와 기본 게이트웨이 주소가 필요하다.

기본 게이트웨이 주소를 브라우저 주소창에 입력하면 관리자 페이지로 이동된다.

근데 나는 IPv4 주소가 보통 사람들과 달랐다!!!
게이트웨이 주소로 접속도 안 됨

우리집은 KT 공유기를 사용하고 있는데 인터넷에 검색해보면 대부분 172로 시작한다.

근데 나는 200?인가 다른 번호로 시작을 하고 기본 게이트웨이 주소로 접속도 안 됐었다

그 이유는 단순..

집에 모뎀 있으신가요? 거기에 꽂혀있는 컴퓨터 랜선을 공유기로 옮겨보세요

옮기고 다시 ipconfig 를 입력해보면 172로 시작하는 주소가 나온다.

바뀐 게이트웨이 주소를 주소창에 입력하면 접속 완!

관리자 페이지

아이디, 비밀번호 모르면 로그인 실패시 계정 재설정 alret이 뜨니 거기서 수정해주면 된다.

바꾼 계정 정보는 혹시 몰라 잘 기록해두었다.

kt 기준으로 포트포워딩은 장치설정-트래픽 관리 메뉴에서 설정해주면 된다.

외부/내부 포트번호 = 1521
내부 IP 주소 = IPv4 주소

를 입력하고 추가하면 된다.

2. 방화벽 설정

제어판\시스템 및 보안\Windows Defender 방화벽 이동 후 고급설정

이름과 옵션은 자유롭게 작성하면 된다.

인바운드 규칙이 만들어졌다!

3. listener.ora 파일 설정

많은 글에서 listener.ora와 tnsnames.ora에서 HOST 주소를 수정하라고 한다.

근데 쳇지피티는 SQL Developer에서 직접 입력하면 되기 때문에 tnsnames.ora는 굳이 수정 안 해도 된다고 한당 ㅇㅅㅇ

결과적으로 나는 listener.ora만 수정해서 성공하긴 했다.

HOST 주소에는 네이버에서 내 ip를 검색해 조회된 주소를 넣어준다.

내IP조회

이 부분에 넣어주면 된다.

이 HOST 주소에 IPv4 주소를 입력하라던가, 컴퓨터 장치 이름을 입력하라고 하는데 나는 다 안 되고

네이버 검색결과로 나온 IP 주소로는 접속이 됐다..

.ora 파일 찾을 때 개큰 꿀팁

내 컴퓨터에서는 많은 블로그들이 말하는 폴더 경로를 따라 파일을 찾을 수가 없어서(왜ㅠ...)

everything 이란걸 설치해서 파일을 찾았다.

https://www.voidtools.com/ko-kr/downloads/

64비트 설치파일 다운 받아 설치했다.

윈도우 파일탐색기 검색을 이용하면 하루 온종일 걸리는데 1초만에 파일을 찾아준다!!

4. 접속 해보기

로컬 환경의 DB는 호스트 이름 localhost로 만들어주고,

외부에서 접속할 때의 호스트 이름에는 listener.ora의 HOST에 입력한 주소와 같은 내IP주소를 입력해준다.

그러면 접속 성공!!

위 과정은 홈서버 띄우기 최종 성공 기록이고

이제는 ORA-17410를 해결한 방법!

분명 원격 DB 접속이 되는걸 확인을 했는데

갑자기 SQL Developer에서 데이터베이스에 접속이 안 되면서 ORA-17410 에러가 떴다.

마지막으로 백엔드 로직을 만지고 있었어서 처음에 쿼리 문제인가 생각했는데
결론은 DB 연결 자체 문제였다.

나는 localhost / 1521 / XE로 접속 중에 이 문제가 발생했다.

서비스로 확인했을 때 OracleServiceXE, OracleXETNSListener도 정상 실행되고 있었다.

이 에러는 간단하게 말해서 DB랑 연결이 끊겼다는 뜻인데

주요 원인은 DB 인스턴스 꺼짐, Listener 문제, 네트워크 문제, 잘못된 접속 정보 등이 있다고..

1. Listener 상태 확인

먼저 Listener 상태부터 확인해준다.

lsnrctl status

터미널을 관리자 권한으로 실행하고 위 명령어를 입력하면

Service "XE"
Instance "XE", status UNKNOWN

이런 결과가 나왔다.

UNKNOWN !!!

이 상태는 Listener는 살아있는데 DB(Oracle XE 인스턴스)가 떠있긴 한데 정상이 아닌 상태

즉, DB가 제대로 OPEN 상태가 아니거나 등록이 안 된 상태이다.

2. DB 재시작으로 1차 해결

SQL*Plus로 접속해서 DB를 재시작한다.

sqlplus / as sysdba
startup;

를 입력하니

ORA-01081: cannot start already-running ORACLE - shut it down first SQL> Disconnected from Oracle Database 11g Express Edition Release 11.2.0.2.0 - 64bit Production

새로운 에러가 발생했다.

이 상황은 DB는 켜져 있는데

“정상적으로 OPEN 상태가 아님” (= mount까지만 됐거나, 뭔가 꼬인 상태) 상태인 것!!!

뭔가 꼬였으니 우리는 재기동을 해주어야한다.

sqlplus / as sysdba

shutdown immediate;
startup;

근데도 결과는 UNKNOWN...

3. 진짜 원인: local_listener 비어있음

이건 동적 등록(dynamic registration)이 안 된 상태였다.

즉, DB는 켜져 있고 Listener도 켜져 있지만 서로 연결(등록)이 안 된 것이다.

Oracle은 Listener에 자동 등록할 때 local_listener 값을 기준으로 연결하는데

이 값이 없거나 틀리면 DB는 살아있는데 Listener는 "누군지 몰라서” UNKNOWN이 뜬다고 한다..

show parameter local_listener;

확실히 value가 비어있었다.

4. 해결: local_listener 설정

alter system set local_listener='(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521))' scope=both;
alter system register;

위 명령어를 차례로 입력해줬고

lsnrctl status

다시 상태를 확인해줬다.

Instance "XE", status READY

드디어 UNKNOWN의 늪에서 벗어나게 됨..

Zustand vs TanStack Query, 같이 쓰자!

vellahw — Sun, 15 Mar 2026 18:16:05 +0900

요즘 프론트엔드 프로젝트에서 Zustand + TanStack Query가 자연스럽게 같이 등장한다.

처음에는 둘 다 상태 관리처럼 보여서 이거 둘 중 하나만 쓰면 되는 거 아닌가? 싶었는데 역할이 완전히 다르다.

이번 글에서는 실제 로그인 플로우를 구현하면서 느낀 차이를 정리해본다.

1. Zustand는 무엇인가?

Zustand는 전역 상태 관리 라이브러리다.
Redux보다 훨씬 간단하고, 보일러플레이트도 거의 없다.

프론트 내부 상태를 저장하는 곳으로,

예를 들면 로그인 모달 열림 여부, 다크모드 상태, 사이드바 열림/닫힘, 사용자가 선택한 탭

이런 것들을 저장한다.

사용예

import { create } from 'zustand'

export const useStore = create((set) => ({
  isOpen: false,
  toggle: () => set((state) => ({ isOpen: !state.isOpen })),
}))

2. TanStack Query는 무엇인가?

TanStack Query 서버 데이터 관리 엔진이다.

즉, API 호출을 중심으로 돌아가는 라이브러리다.

단순히 fetch만 하는 게 아니라

캐싱, 자동 재요청, 로딩 상태 관리, 에러 처리, 데이터 동기화 등

이런걸 전부 알아서 해준다.

예를 들어 로그인 상태를 확인하는 API가 있다고 해보자.

import { useQuery } from '@tanstack/react-query'
import axios from 'axios'

export const useAuthQuery = () => {
  return useQuery({
    queryKey: ['auth'],
    queryFn: async () => {
      const res = await axios.get('/api/auth/me', {
        withCredentials: true,
      })
      return res.data
    },
    retry: false,
  })
}

이 한 줄로 “로그인 상태 + 캐싱 + 로딩 + 에러 처리”가 다 해결된다.

3. 둘의 차이 한 번에 정리

구분	Zustand	TanStack Query
역할	클라이언트 상태	서버 상태
데이터 위치	브라우저	서버
주요 기능	상태 저장	API 관리
로딩/에러	직접 구현	자동 제공

핵심은 “데이터가 어디에서 왔느냐”

서버에서 왔다 → TanStack Query
프론트에서 만든 상태다 → Zustand

4. 로그인 구현에서의 실제 차이

카카오 로그인 기반으로 구현하면서 이 차이가 더 명확해졌다.

1. 로그인 성공 → accessToken, refreshToken 쿠키 저장
2. 프론트는 토큰을 읽을 수 없음 (httpOnly 쿠키)
3. API로 로그인 여부 확인

여기서 중요한 포인트, 로그인 여부는 서버에 물어봐야 한다는 것

즉, 이건 Zustand가 아니라 TanStack Query 영역이다.

올바른 구조

처음엔 Zustand에 유저 상태를 저장하려고 했다.

그렇게 하면 문제는 페이지 이동마다 API를 호출 해야하고, 동기화가 깨지며 상태가 꼬인다.

그래서 TanStack Query에는 서버 상태를 저장하고, Zustand에는 UI 상태를 저장하는 구조로 바꾸는 게 맞다!

1. TanStack Query → 서버 상태

const { data, isLoading, isError } = useAuthQuery()

로그인 여부 판단
유저 정보 가져오기
자동 캐싱

2. Zustand → UI 상태

isLoginModalOpen: false
toggleLoginModal: () => {}

모달 열림 여부
UI 상태 관리

5. 실제 흐름

최종적인 로그인 흐름:

브라우저 접속 (/)
→ 로그인 검증 API 요청
→ 서버가 로그인 여부 판단
→ TanStack Query가 결과 관리
→ 라우팅 분기 (/home 또는 /login)

여기서 Zustand는 등장하지 않는다.

결론

처음엔 둘 다 상태 관리처럼 보여서 헷갈리지만
실제로 써보면 완전히 다른 도구라는 걸 알게 된다.

서버 데이터는 TanStack Query로 관리
UI 상태는 Zustand로 관리

이 구조로 가면 코드가 훨씬 단순해지고,
특히 로그인 같은 인증 로직이 안정적으로 돌아간다.

기존 Vite + React 프로젝트에 TypeScript 추가하기 (마이그레이션 정리)

vellahw — Thu, 12 Mar 2026 16:58:25 +0900

사이드 프로젝트를 새로 시작했다.

기존에 세팅은 되었던 프로젝트라, Vite + React(JavaScript) 프로젝트에 TypeScript를 추가하면서 겪었던 과정과 필요한 설정을 정리해보았다.

1. TypeScript 설치

먼저 프로젝트에 TypeScript와 React 타입을 설치한다.

npm install -D typescript @types/react @types/react-dom

설치가 완료되면 TypeScript 설정 파일을 생성한다.

npx tsc --init

그러면 프로젝트 루트에 tsconfig.json 파일이 생성된다.

2. tsconfig.json 설정

기본 생성된 tsconfig.json을 Vite 환경에 맞게 일부 수정했다.

{
  "compilerOptions": {
    "target": "ESNext",
    "lib": ["DOM", "DOM.Iterable", "ESNext"],

    "module": "ESNext",
    "moduleResolution": "Bundler",

    "jsx": "react-jsx",

    "strict": true,
    "skipLibCheck": true,

    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,

    "allowJs": true
  },
  "include": ["src"]
}

✅주요 옵션

- strict

TypeScript의 타입 검사를 엄격하게 한다.

- allowJs

기존 JavaScript 파일을 그대로 사용할 수 있게 해준다.
기존 프로젝트에 TypeScript를 도입할 때 유용함. 파일이 많을 때는 중요!

- moduleResolution: Bundler

Vite 환경에 맞는 모듈 해석 방식

3. vite-env.d.ts 생성

Vite 프로젝트에서는 환경 변수 타입을 위해
vite-env.d.ts 파일이 필요하다.

src 폴더 안에 아래 파일을 생성하고 내용은 다음과 같다.

/// <reference types="vite/client" />

이 파일이 있어야 import.meta.env.VITE_API_URL 같은 코드에서 타입이 정상적으로 작동한다.

4. vite.config.js → vite.config.ts 변경

Vite 설정 파일도 TypeScript로 변경할 수 있다.

vite.config.js → vite.config.ts

5. main 파일 먼저 TypeScript로 변환

기존 프로젝트를 TypeScript로 마이그레이션할 때는 entry 파일부터 변환하는 것이 좋다고 한다.

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

여기서 !는 Non-null assertion으로
root 요소가 null이 아니라는 것을 TypeScript에게 알려주는 역할을 한다.

main 이후로는 App 컴포넌트, 다른 컴포넌트들을 하나씩 변환해주면 된다.

기존 프로젝트를 TypeScript로 마이그레이션할 때는 보통 이러한 순서로 진행하는 것이 좋다고.. (아무래도)

타입 정의

1. Props 타입 정의

컴포넌트를 TypeScript로 변환할 때는 Props 타입을 정의해준다.

type ButtonProps = {
  children: React.ReactNode;
  onClick?: () => void;
};

export function Button({ children, onClick }: ButtonProps) {
  return <button onClick={onClick}>{children}</button>;
}

이렇게 하면 컴포넌트를 사용할 때 타입 체크가 가능해진다.

2. API 타입 정의

API 데이터를 사용할 때도 타입을 정의해준다.

interface User {
  id: number;
  name: string;
}

axios 요청에서도 타입을 지정할 수 있다.

axios.get<User[]>("/api/users");

실무에서는 위처럼 정의한 타입을 별도 폴더로 관리하는 경우가 많다.

src
 ├ components
 ├ hooks
 ├ api
 ├ types
 ├ utils
 └ pages

src/types/user.ts

export interface User {
  id: number;
  name: string;
}

마무리

기존 Vite + React 프로젝트에 TypeScript를 적용할 때 필요한 과정

TypeScript 설치
tsconfig.json 생성 및 설정
vite-env.d.ts 생성
vite.config.ts 변환
main.tsx부터 변환
컴포넌트를 하나씩 TypeScript로 변환
Props와 API 타입 정의

처음에는 번거롭게 느껴질 수 있지만
프로젝트 규모가 커질수록 TypeScript의 장점이 크게 느껴진다.

앞으로는 새 프로젝트를 만들 때
처음부터 React + TypeScript로 시작하는 것이 더 좋은 선택일 것 같다.

Git 커밋 이력 변경하기 (작성자, 날짜 수정하기)

vellahw — Fri, 19 Dec 2025 14:32:57 +0900

Git을 사용하다 보면 커밋 메시지를 잘못 작성했거나 민감한 정보가 커밋에 포함된 경우처럼 커밋 이력을 수정해야 하는 상황이 생긴다.

나는 내 개인 레포지토리에 회사 계정으로 커밋을 해버렸다. Contributors에도 회사 계정이!..

회사PC를 사용하면서 유저를 변경하지 않고 신나게 커밋해버린 실수..

이 글에서는 여러개의 커밋 이력을 변경하는 방법을 정리했다.

⚠️ 주의: 나는 나 혼자 쓰는 개인 레포였지만, 공유 브랜치에서 작업할 경우 팀원들에게 큰 영향을 줄 수 있으므로 반드시 주의할 것!

참고) VSCode 기준 Git Bash 터미널에서 진행했다.

1. 유저 변경

git config --global user.name 유저이름 
git config --global user.email 유저이메일

우선 위 명령어를 차례로 입력해 유저 정보를 변경한다.

(--global 옵션은 전역 설정이기 때문에 해당 레포지토리 한정으로 유저를 변경할 거라면 --global 생략 가능)

git config user.name
git config user.email

잘 변경되었는지는 위 명령어들로 확인하면 된다

2. 로그 확인 후 리베이스

git log 명령어로 히스토리를 확인해주고

git rebase -i --root

위 명령어로 리베이스를 실행한다.

나는 첫번째 커밋부터 전부 다 변경해야 되는 상황이었어서 --root 옵션을 사용했다.

--root 자리에 HEAD~n 이런식으로 작성하면 가장 최근 커밋부터 n개의 커밋을 선택할 수 있다.

명령어를 입력하면 위처럼 로그를 확인할 수 있는데

e 라고 써진 부분은 원래 pick 이 써져있다.

i 를 입력하여 작성 모드로 들어간 후,

수정이 필요한 커밋 내역들을 사진처럼 pick 을 e 혹은 edit 으로 수정해준다.

그후 esc → :wq 를 입력하여 모드를 빠져나온다

그럼 사진처럼 commit 을 할건지 rebase를 할건지 선택하라고 하는데

우리는 작성자(+날짜)를 변경해줘야 하기 때문에

git rebase --continue

명령어를 입력해 다시 리베이스를 실행한다.

그럼 사진과 같이 한 개의 커밋 이력이 보일 것이다.

3. 작성자 변경하기

 git commit --amend --author="Author Name<author@email>"

위 명령어를 입력해 작성자를 수정해준다.위 명령어를 입력하면 아까 pick을 e로 바꿔주었던 창이 또 뜨는데, 거기서 커밋메세지를 수정할 수도 있다.

수정할게없으면 --amend 뒤에 --no-edit 옵션을 붙이면 된다.

 git commit --amend --no-edit --author="Author Name<author@email>"

3-1. 날짜 변경하기

작성자만 변경하면 된다면 4번으로 넘어가 push 해주면 된다.

하지만 나는 커밋 수정을 한 번 잘못 하는 바람에 날짜 수정을 추가로 진행했다.

GIT_COMMITTER_DATE="Tue Dec 9 11:09:48 2025 +0900" git commit --amend --no-edit --date "Tue Dec 9 11:09:48 2025 +0900"

GIT_COMMITTER_DATE 변수를 만들어 날짜를 수정해준다.

쌍따옴표 안에 요일 월 등 Git 형식에 맞춰 날짜 값을 입력해주면 된다.

작성자 수정할 때와 마찬가지로 --no-edit 옵션 유무는 선택하면 된다.

커밋 반영

위 git rabase 부터 --amend 수정 과정을 반복하면 사진처럼 Successfully~ 문구가 나온다.

그럼 이제 모든 커밋의 수정이 완료된 것! push 만 해주면 끝난다.

git push --force

⚠️ 주의: 개인 레포가 아닌 공유 브랜치에서 force push 하지 않도록 주의해야한다

참고

https://hirlawldo.tistory.com/156

https://sangminlog.tistory.com/entry/modify-author

모바일 UI 디자인 시스템과 프론트엔드에서 디자인 시스템 적용하기

vellahw — Sat, 20 Jan 2024 18:56:39 +0900

서론

요즘 휴대폰의 화면비율은 정말 다양하다.

미니 사이즈의 선호도가 줄고 휴대폰의 평균 사이즈가 커졌어도 작은 기종을 고려하지 않을 수 없다.

어떤 기기는 세로 길이가 667px 정도로 작고, 어떤 기기는 882px 이상으로 꽤 크다.

그래서 디자인 시안을 바탕으로 프론트엔드 개발을 하다 보면 이런 고민이 생긴다.

UI 요소 크기는 작은 화면 기준으로 해야 할까? 큰 화면 기준으로 해야 할까?
작은 사이즈에서는 페이지 디자인이 "예뻐"보이는데 큰 사이즈에서는 적절하지 않아보인다면.. 어떻게 해야할까?

고민을 바탕으로

모바일 UI를 디자이너 관점에서 어떻게 설계하는지
그리고 프론트엔드에서 디자인 시스템을 어떻게 구현하는지

를 가볍게 정리해보았다.

1. 모바일 UI는 어떤 화면 기준으로 디자인할까?

웹 디자인을 배워보질 않았으니 쳇지피티에게 물어본 결과

결론부터 말하면 보통 작은 화면 기준으로 설계한다고 한다.

그 이유는

작은 화면에서 UI가 깨지면 복구가 거의 불가능하고

큰 화면은 여백이나 레이아웃 확장으로 대응 가능하기 때문이다.

✅ 고정되는 UI

버튼 높이, 터치 영역, 아이콘 사이즈, 텍스트 크기 등

사용성에 직접적인 영향을 주는 요소는 고정된다.

button height = 48px
icon = 24px
body text = 16px

✅ 유동적으로 늘어나는 것

섹션 간격, hero 영역, 카드 간격, 여백 등

레이아웃 요소들은 보통 유동적으로 확장된다.

예를 들면 이런 식

// 작은 화면
section spacing = 24px
hero height = 220px

// 큰 화면
section spacing = 40px
hero height = 320px

핵심은 콘텐츠는 유지하고 여백을 확장한다는 것

2. 모바일 디자인에서 많이 쓰는 기본 규칙

✅ 8pt Spacing System

모바일 UI에서는 보통 8pt 시스템을 사용한다.

예시

icon ↔ text = 8
card padding = 16
section gap = 24

✅ 터치 영역 규칙

터치 영역 규칙은 모바일 UX에서 중요한 규칙이다.

최소 터치 영역 = 44px
버튼 높이 = 48~56px
아이콘 = 24px

3. 프론트엔드에서 디자인 시스템 적용하기

일반 CSS 기준에서 디자인 시스템은

디자인 토큰 → 공통 스타일 → 컴포넌트 스타일 구조로 정의하는 것이 일반적이다.

핵심 목적은 일관성 있는 UI 스타일을 유지하고 재사용성을 높이는 것이다.

1) 디자인 토큰 정의

디자인 시스템의 가장 기초 단계는 디자인 토큰이다.
색상, 간격, 폰트 같은 기본 스타일 값을 변수로 관리한다.

CSS에서는 보통 CSS Custom Properties (CSS 변수)로 정의한다.

:root {
  /* color */
  --color-primary: #111111;
  --color-secondary: #666666;
  --color-background: #ffffff;

  /* spacing */
  --space-xs: 4px;
  --space-sm: 8px;
  --space-md: 16px;
  --space-lg: 24px;

  /* radius */
  --radius-sm: 4px;
  --radius-md: 8px;

  /* font */
  --font-body: 16px;
  --font-title: 24px;
}

이렇게 정의하면 프로젝트 전체에서 동일한 값을 재사용할 수 있다.

2) 리셋 및 글로벌 스타일 정의

브라우저 기본 스타일을 제거하고 기본 레이아웃 규칙을 설정한다.

모든 UI 컴포넌트의 기본 스타일 환경을 통일시킨다.

*,
*::before,
*::after {
  box-sizing: border-box;
}

html,
body {
  margin: 0;
  padding: 0;
}

body {
  font-family: system-ui, sans-serif;
  font-size: var(--font-body);
  color: var(--color-primary);
}

3) 타이포그래피 시스템 정의

.text-body {
  font-size: 16px;
  line-height: 1.5;
}

.text-title {
  font-size: 24px;
  font-weight: 600;
}

.text-caption {
  font-size: 12px;
  color: var(--color-secondary);
}

본문, 제목, 설명글 등

텍스트 스타일을 공통 클래스로 정의한다.

4) 레이아웃 시스템 정의

페이지의 공통 레이아웃 규칙을 만든다. 대표적인 예가 container와 spacing 시스템이다.

✅ container

.container {
  width: 100%;
  max-width: 1200px;
  margin: 0 auto;
  padding: 0 var(--space-md);
}

container는 레이아웃에서 자주 등장하는 패턴이다.

container는 페이지 콘텐츠의 가로 폭과 좌우 여백을 통제한다.

예를 들어 화면이 너무 넓으면 엔터 없이 작성된 글처럼 가독성이 떨어진다.

그래서 max-width가 지정된 container를 사용하는 것!

✅ stack (vertical layout)

.stack > * + * {
  margin-top: var(--space-md);
}

이런 패턴은 컴포넌트 사이 간격을 일정하게 유지하는 데 사용한다.

5) 컴포넌트 스타일 정의

UI 요소를 재사용 가능한 클래스로 정의한다.

✅ 버튼 예시

.button {
  display: inline-flex;
  align-items: center;
  justify-content: center;

  height: 40px;
  padding: 0 var(--space-md);

  border-radius: var(--radius-md);
  border: none;
  cursor: pointer;
}

variant는 modifier 클래스로 정의한다.

.button--primary {
  background: var(--color-primary);
  color: white;
}

.button--secondary {
  background: transparent;
  border: 1px solid var(--color-primary);
}

사용 예

<button class="button button--primary">
  확인
</button>

이 구조는 보통 BEM 방식이라고 부른다.

6) 상태 스타일 정의

.button:hover {
  opacity: 0.9;
}

.button:disabled {
  opacity: 0.4;
  cursor: not-allowed;
}

상태 스타일은 pseudo class(의사/가상 클래스)로 관리하는 것이 일반적

7) 반응형 규칙 정의

반응형 스타일은 breakpoint 기준으로 관리한다.

.container {
  padding: 0 var(--space-sm);
}

@media (min-width: 768px) {
  .container {
    padding: 0 var(--space-lg);
  }
}

대부분 모바일 퍼스트 방식으로

모바일(max-width: 767px)이 기본값 → min-width로 확장하는 패턴을 쓴다.

8) 파일 구조

위 내용을 바탕으로 디자인 시스템을 정의하면 이러한 파일 구조가 완성된다.

styles
 ├ reset.css
 ├ tokens.css
 ├ typography.css
 ├ layout.css
 └ components
  ├ button.css
  ├ card.css
  └ input.css

정리

디자이너가 만든 규칙을 토큰으로 강제하면

UI 일관성이 유지되고
유지보수가 쉬워지고
팀 협업이 훨씬 편해진다.

프론트엔드에서 디자인 시스템을 잘 만들어 두면 UI 개발 속도가 정말 많이 빨라질 것이다.

위처럼 정리한 구조를 따르면 디자인 일관성을 유지하면서 확장 가능한 CSS 아키텍처를 만들 수 있을 것이다!

CSS position: sticky 제대로 이해하기 (왜 고정이 안 될까?)

vellahw — Tue, 12 Dec 2023 01:29:55 +0900

서론

여태 브라우저의 헤더나 하단 바를 만들 때는 보통 position: fixed를 사용해왔다.

그런데 무신사나 지그재그 웹 브라우저처럼 레이아웃이 모바일 사이즈(max-width)로 고정된 구조에서는

fixed를 사용하면 요소가 max-width로 제한된 레이아웃을 벗어나 좌우 바깥으로 튀어나오는 현상이 생긴다.

( fixed는 뷰포트 기준으로 고정되기 때문 )

지그재그 웹을 살펴보니 헤더에 position: sticky가 사용되고 있었다.

그래서 같은 방식으로 sticky를 적용해봤지만 고정이 안 됐다.

같은 sticky 속성을 사용했는데 왜 고정이 안 될까?

원인을 찾는 과정에서 별거 아닌 내용일 수도 있지만 작은 CSS 동작 원리를 하나 새롭게 알게 되어 정리해본다.

결론)

position: sticky는

✔ top, left 등 기준값 필수
✔ 부모 요소에 overflow 사용 X

1. position: sticky란?

position: sticky는 relative와 fixed의 중간 개념

기본 상태에서는 일반 문서 흐름(relative)처럼 동작
스크롤이 특정 위치에 도달하면 고정(fixed)처럼 동작

즉, 스크롤 위치에 따라 동적으로 고정되는 포지션이다.

기본 사용 예시

.header {
  position: sticky;
  top: 0;
}

동작 방식:

처음에는 일반 요소처럼 배치
스크롤해서 요소가 top: 0 위치에 도달하면
해당 위치에 붙어서 고정

따라서 top, left, right 등의 기준값을 함께 작성해야함!

2. sticky와 fixed의 차이

속성특징

position: fixed	화면(Viewport) 기준으로 항상 고정
position: sticky	부모 영역 내부에서만 고정

예를 들어 사이드바에 sticky를 사용하면

스크롤할 때 따라 내려오다가
부모 영역 끝에 도달하면 멈춘다.

3. position: sticky가 동작하지 않는 대표적인 이유

1️⃣ top, left 등의 기준 값이 없음

sticky는 기준 위치가 반드시 필요하다.

top, bottom, left, right 중 하나는 반드시 지정해야 한다.

2️⃣ 부모 요소에 overflow 속성이 있음

나는 부모 요소의 overflow 때문에

3️⃣ Flex / Grid 레이아웃 환경 문제

flex 컨테이너 안에서 sticky가 제대로 작동하지 않는 경우도 있다.

이 경우 다음 속성을 추가해 해결한다.

.sticky-element {
  align-self: flex-start;
}

"리액트는 가상 DOM을 사용하여 성능을 최적화합니다." 가 무슨 말이야?

vellahw — Wed, 13 Sep 2023 14:49:04 +0900

서론

프론트엔드를 공부하다 보면 한 번쯤은 이런 문장을 보게 된다.

“리액트는 가상 DOM(Virtual DOM)을 사용하여 성능을 최적화합니다.”

그런데 처음 보면 이게 무슨 말인지 꽤 추상적으로 느껴진다.
이 문장이 실제로 무엇을 의미하는지, 그리고 왜 성능이 좋아지는지 정리해보았다.

1. DOM이란 무엇인가?

먼저 DOM(Document Object Model)부터 이해해야 한다.

웹페이지는 내부적으로 DOM 구조로 관리되는데, 쉽게 말하면

브라우저는 우리가 작성한 HTML을 그대로 사용하는 것이 아니라
트리 구조의 객체 형태(DOM)로 변환해서 관리한다.

예를 들어

<body>
  <h1>제목</h1>
  <p>내용</p>
</body>

이 코드는 브라우저 내부에서 다음과 같은 구조로 관리된다.

body
- h1
- p

이러한 구조를 DOM이라고 한다.

2. 문제: DOM을 직접 수정하면 느리다

웹에서 버튼 클릭, 데이터 변경, 입력값 변경 등으로 상태가 바뀌면 화면도 바뀌어야 한다.

이때 가장 직관적인 방식은 DOM을 직접 수정하는 것이다.

하지만 문제는

DOM 수정은 비용이 크고
화면을 다시 계산해야 하고 (reflow)
다시 그려야 한다 (repaint)

즉, DOM을 자주 건드릴수록 성능이 떨어진다.

3. 해결 방법: 가상 DOM (Virtual DOM)

리액트는 이 문제를 해결하기 위해 가상 DOM(Virtual DOM)이라는 개념을 사용한다.

가상 DOM이란 실제 DOM을 흉내 낸 “자바스크립트 객체” 를 말한다.

사용자가 웹 애플리케이션을 열면 리액트는 초기 UI를 생성한다.
실제 DOM을 만드는 대신 가상 DOM 트리를 만드는데,

가상 DOM은 메모리에 존재하며 실제 화면에 표시되지 않는다.

즉, 리액트는 브라우저의 DOM을 직접 건드리지 않고
메모리 안에서 가짜 DOM을 하나 더 만들어서 작업한다.

4. 리액트의 동작 방식

기존 방식은 변경이 발생할 때마다 DOM을 직접 수정하기 때문에 비효율적이고 느리다.

하지만 리액트 방식은

①

사용자가 어떤 상태 변경을 트리거(예: 버튼 클릭)하면,

리액트는 해당 변경을 감지하고 새로운 가상 DOM 트리를 생성한다.

이 트리에는 변경된 상태를 반영한 UI 요소가 포함된다.

②

이제 리액트는 이전 가상 DOM 트리와 새로운 가상 DOM 트리를 비교한다.

(이 과정을 "재조정" 또는 "린더링"이라고 한다.)
리액트는 두 가상 DOM 트리를 비교하면서 어떤 부분이 변경되었는지를 효율적으로 찾는다.

③

변경된 부분만을 찾아내면, 리액트는 이 부분만을 실제 DOM에 반영한다.

이전과 새로운 가상 DOM 사이의 변경된 부분만을 조작하므로

전체 페이지를 다시 렌더링하지 않고도 업데이트가 가능하다.

정리하자면

상태(state)가 변경됨
새로운 가상 DOM 생성
이전 가상 DOM과 비교
변경된 부분만 실제 DOM에 반영

위와 같은 흐름으로 동작한다.

이것은 브라우저가 실제 DOM 조작에 비해 빠르게 처리할 수 있도록 도와주는 것이다.

5. 가상 DOM이 성능이 좋아지는 이유

기존 방식은 집을 고칠 때 전체를 다 부수고 다시 짓는 느낌이라면

리액트는 고장난 부분만 찾아서 고치는 느낌으로 비유할 수 있다.

가상 DOM이 성능이 좋아지는 이유의 핵심은 딱 하나다.

실제 DOM 접근을 최소화하기 때문

리액트는 Virtual DOM을 이용해 변경 사항을 비교한 뒤,

화면을 통째로 다시 그리지 않고, 바뀐 부분만 효율적으로 업데이트해서 빠르게 만든다.

(필요한 부분만 실제 DOM에 반영함으로써 성능을 최적화한다.)

정리

이러한 과정을 통해 리액트는 렌더링 성능을 최적화한다.

전체 페이지를 다시 렌더링하지 않고도 변경된 부분만을 업데이트하므로

사용자에게 빠른 응답성을 제공하면서도 불필요한 계산과 DOM 조작을 최소화한다.

가상 DOM은 단순한 개념처럼 보이지만 리액트의 전체를 이해하는 핵심이라고 볼 수 있는 것 같다.