망각의 코딩러 흐성진

React + Vite 프로젝트에 GA4(Google Analytics) 설정하기

흐성진 — Wed, 17 Dec 2025 18:38:02 +0900

주제 선정

요즘 개인 프로젝트나 사이드 프로젝트를 진행하다 보면 "사용자가 어떻게 서비스를 사용하고 있는가?" 에 대한 궁금중이 컸고, 해당 데이터가 중요하다는걸 많은 순간에 느끼게 된다.

단순히 화면을 잘 만들고 기능을 구현하는게 끝이 아니라 실제로 어떤 페이지가 자주 방문되는지? 어디에서 이탈이 발생하는지? 어떤 행동 흐름을 보이는지? 를 기반으로 개선 방향을 잡아야 하기 떄문이다.

이런 맥락에서 가장 많이 활용되는 도구가 바로 Google Analytics 4(GA4) 이다.

GA4는 기존 Universal Analytics와 달리 이벤트 중 심의 분석 구조를 가지고 있고, 사용자 행동을 더 유연하고 세밀하게 추적할 수 있다는 장점이 있다.

하지만 막상 프론트엔트 프로젝트에 적용하려고 하면 초기 설정부터 이벤트 연동 단계에서 생각보다 어렵게 느껴진다.

이번 글에서는 React + Vite로 구성된 프로젝트 이며 FSD 관점을 기준으로 GA4를 어덯게 연동하고 기본적인 설정을 진행할 수 있는지 정리해 보려고한다.

GA4 이벤트 중심 모델 이해하기

GA4의 가증 큰 특징은 모든 데이터가 이벤트 기반이라는 점이다.

기존 Universal Analytics 에서는

- 페이지뷰

- 이벤트

- 사용사 속성

이 비교적 명확하게 구분되어 있었지만

반면 GA4에서는 페이지뷰 조차 하나의 이벤트로 취급된다.

이렇게 이벤트로 취급하게 되면 오는 이점이

- 페이지가 아닌 행동 중심 분석이 가능하다

- 동일한 방식으로 클릭, 전환, 에러, 스크롤 등을 추적할 수 있다.

- 커스텀 이벤트 설계가 훨씬 자유롭다

하지만 이렇게 장점만 있는건 아니고

아무 이벤트나 막 보내게되면 나중에 분석하기 오히려 더 어려워진다.

그러므로 프론트엔트 코드 레벨에서 이벤트 구조를 적절하게 통제하는 것이 중요하다.

Google Analytics 만들기

기본적인 GA4를 사용하기위해서는 Google Analytics 에 접속해서 속성을 생성해주오야한다.

1. 속성 이름 설정

속성에서 사용할 이름을 설정해준다.

2. 업종 및 카테고리, 규모 설정

업종 및 카테고리와

비즈니스의 규모를 목적에 맞게 설정해준다

3. 비즈니스 목표 설정

아래의 항목에서 나에게 맞는 비즈니스 목표를 설정해주면 된다

4. 데이터 스트림 설정

내가 적용하고자 하는 웹사이트의 주소와 별칭을 입력해준다

5. 스트림 ID, 측정 ID 확인

위의 단계를 거치면 다음과 같이 웹 스트림 세부정보를 얻을 수 있는데

여기서 측저에 필요한 스트림 ID, 측정 ID를 가져올 수 있다.

해당 ID값들을 가지고 이제 React와 연결해주도록한다.

왜 GA4를 코드 레벨에서 관리해야 할까?

GA4는 단순히 붙여두면 알아서 수집되는 분석 도구가 아니다.

실제로 Google Analytics에 접속해서 속성을 만들게 되면 코드를 index.html 에 붙여넣으라고 안내를 받는다.

하지만 그렇게 하면 실제로 어떤 이벤트에 대한 세세한 설정이 어렵다는 단점이 있다.

그래서 단순하게 GA4 코드 붙여넣기가 아니라 FSD 구조에서 GA4를 어디에 두는게 적절한지

페이지뷰, 이벤트, 사용자 속성은 어떻게 분리하면 좋은지

에 대한 고민을 하게되면 코드 레벨에서 관리를 해야 이점이 있다고 느끼게된다.

React와 연결하기

이제 FSD 아키텍쳐 구조에 맞게 파일을 구성해보려고한다.

ID값 같은 경우 노출에 대해서는 최대한 피하는 방향으로 .env파일 안에 위치시키려고한다.

.env 파일 안에는 이전에 받아온 G로 시작하는 측정 ID를 넣어주면 된다

VITE_GA_MEASUREMENT_ID=G-XXXXXXXXXX

GA4와 관련된 내용은 Shared 레이어로 src/shared/analytics 의 폴더를 만들고 그 하단에 구성해보려고한다.

여기서 왜 Shared 레이어에 넣는지 의문이 들수도 있다.

이벤트들은 어디서든 발생하게 된다.

유저가 로그인할때 (로그인 페이지)

유저가 페이지 이동할때 (각 페이지)

API에 대한 에러를 추적할때 (각 API)

이렇게 다양하게 애플리케이션 전반적으로 사용되는 공통 인프라에 가깝다.

그래서 Shared 레이어에 위치 시켰다.

react-ga4 설치

https://www.npmjs.com/package/react-ga4

정확한 측정을 위해서 react-ga4라이 브러리를 설치한다

yarn add react-ga4

or

npm i react-ga4

이벤트 타입 정의

위치 : src/shared/analytics/types.ts

라이브러리의 작성된 값을 토대로 파라미터를 정의해 준다.

이벤트 구조를 명시적으로 통제하고 설계가 산발적으로 퍼지는 것을 방지하고 추후 이벤트 네이밍 컨벤션 통일을 위해 별도의 타입으로 정의해주었다.

// 이벤트 파라미터 타입 정의
export interface GAEvent {
  category: string;
  action: string;
  label?: string;
  value?: number;
}

export interface GAPageView {
  path: string;
  title?: string;
}

GA4 초기화 및 핵심 함수

위치 : src/shared/analytics/ga4.ts

타입을 정의했다면 이제 GA4를 사용하기 위해 초기화를 시키고 그 안에서 사용할 핵심 함수에 대해서 정의를 해줘야한다.

import ReactGA from "react-ga4";
import { GAEvent } from "./types";

// GA4 측정 ID (환경변수로 관리)
const GA_MEASUREMENT_ID = import.meta.env.VITE_GA_MEASUREMENT_ID || "";

/**
 * GA4 초기화
 */
export const initGA = () => {
  if (!GA_MEASUREMENT_ID) {
    console.warn("GA4 Measurement ID가 설정되지 않았습니다.");
    return;
  }

  ReactGA.initialize(GA_MEASUREMENT_ID, {
    gaOptions: {
      // 디버그 모드 (개발 환경에서만)
      debug_mode: import.meta.env.DEV,
    },
    gtagOptions: {
      // 쿠키 설정
      cookie_flags: "SameSite=None;Secure",
    },
  });

  console.log("GA4 초기화 완료");
};

/**
 * 페이지뷰 추적
 */
export const trackPageView = (path: string, title?: string) => {
  if (!GA_MEASUREMENT_ID) return;

  ReactGA.send({ 
    hitType: "pageview", 
    page: path,
    title: title || document.title,
  });
  
  console.log("GA4 PageView:", path, title);
};

/**
 * 이벤트 추적
 */
export const trackEvent = (event: GAEvent) => {
  if (!GA_MEASUREMENT_ID) return;

  ReactGA.event({
    category: event.category,
    action: event.action,
    label: event.label,
    value: event.value,
  });

  console.log("GA4 Event:", event);
};

/**
 * 사용자 속성 설정
 */
export const setUserProperties = (properties: Record<string, string | number>) => {
  if (!GA_MEASUREMENT_ID) return;

  ReactGA.gtag("set", "user_properties", properties);
};

App.tsx에서 GA4 초기화

App.tsx에서 이전에 만들었던 ga4.ts 의 initGa를 호출해주어 초기화를 시켜주어야 한다.

import { useEffect } from "react";
import { AppRouter } from "./router";
import { ToastProvider, AlertProvider } from "@shared/ui";
import { initGA } from "@shared/analytics";

export function App() {

  useEffect(() => {
    initGA();
  }, []);

  useEffect(() => {
    const handleContextMenu = (e: MouseEvent) => {
      e.preventDefault();
    };

    document.addEventListener("contextmenu", handleContextMenu);

    return () => {
      document.removeEventListener("contextmenu", handleContextMenu);
    };
  }, []);

  return (
    <ToastProvider>
      <AlertProvider>
        <AppRouter />
      </AlertProvider>
    </ToastProvider>
  );
}

정상적으로 호출이 완료되었다면 다음과 같이 초기화 완료 메시지가 뜨고

Google Analytics에 들어가게되면 다음 이미지와 같이 활성 사용자가 잡히게된다

Router에서 페이지뷰 추적

이렇게 기초적인 세팅을 끝내고 난 다음 해야되는게 무엇일까?

유저가 어던 페이지에 접속하여있는지 알아내야한다.

그러기 위해선 Router 내부에서 어떤 페이지에 접근하는지 알려주도록한다.

아래 코드와 같이 필요 훅들과 컴포넌트를 작성해주고

AppRouter 의 BrowserRouter의 하단에 작성하도록 한다

Router 레벨에서 페이지뷰를 추적하는 이유는

SPA환경에서는 페이지가 바꿔도 브라우저의 새로고침이 발생하지 않기 때문에

GA입장에서는 사용자가 페이지를 이동했다는 사실을 명시적으로 알려줘야 하기 떄문이다.

import { trackPageView } from "@shared/analytics";

// 페이지뷰 추적 훅
function usePageTracking() {
  const location = useLocation();

  useEffect(() => {
    trackPageView(location.pathname + location.search);
  }, [location]);
}

// 페이지 추적 컴포넌트
function PageTracker() {
  usePageTracking();
  return null;
}


export function AppRouter() {
  return (
    <BrowserRouter>
      <PageTracker />
    </BrowserRouter>
  );
}

이렇게 페이지 뷰를 추적하도록 했다면

trackingPageView에 따라서 어떤 페이지에 접근했는지 확인할 수 있다.

이벤트 추적하기

사용자가 특정 버튼을 누른경우, 특정 폼을 제출한 경우, 또는 에러를 추적하는 경우에 다음과 같이 추적할 수 있다.

import { trackEvent } from "@shared/analytics";

// 버튼 클릭 추적
const handleLoginClick = () => {
  trackEvent({
    category: "User",
    action: "Login",
    label: "Login Button",
  });
  // 로그인 로직...
};

// 폼 제출 추적
const handleFormSubmit = () => {
  trackEvent({
    category: "Form",
    action: "Submit",
    label: "Timetable Creation",
  });
  // 폼 제출 로직...
};

// 에러 추적
const handleError = (error: Error) => {
  trackEvent({
    category: "Error",
    action: "API Error",
    label: error.message,
  });
};

그럼 여기서 이벤트 추적은 언제, 어디까지 할까 의문이 들 수 있다.

무조건 많은 이벤트를 추적한다고 해서 좋은 코드는 아니다.

- 핵심 CTA 클릭

- 전환과 직접적으로 연결된 액션

- 사용자가 의사결정 을 하는 순간

- 에러, 실패 케이스

와 같은 경우에는 추적하면 분석에 좋은 포인트들이다.

하지만 모든 버튼, 단순 UI 인터렉션, 분석 목적이 불분명한 이벤트는 피하는 방향이 좋다.

이벤트 하나하나가 나중에 이 데이터를 보고 어떤 판단을 할 수 있는가? 에 대해서 답변이 가능한 이벤트 들에만 사용하는 것이 좋은 방식이다.

결론

GA4는 단순히 방문자 수를 확인하는 도구가 아니라,

사용자의 실제 행동을 이해하기 위한 도구에 가깝다.

내 프로젝트에서 어떤 기능이 자주 사용되는지, 어느 지점에서 이탈이 발생하는지

그리고 우리가 의도한 흐름이 실제 사용자에게도 자연스럽게 이어지고 있는지를 데이터로 확일할 수 있게 해준다.

이번 글에서는 React + Vite 환경에서 Ga4를 단순히 연동하는 방법을 FSD 구조를 기준으로 분석 로직을 어떻게 분리하고 관리할 수 있는지 초점을 맞췄다.

shared/analytics 레이어에 GA4관련 로직을 모아두면서 페이지뷰, 이벤트, 사용자 속성을 공통 인터페이스로 관리하면 프로젝트가 커지더라고 추적 구조가 유지된다.

또한 Router 레벨에서 페이지 뷰를 추적하고 필요한 지점에서만 명확한 의미를 가진 이벤트를 정의함 으로써 불필요한 로그를 줄이고 실제로 판단에 도움이 되는 데이터에 집줄할 수 있다.

이번 세팅을 시작으로 전환 이벤트, 커스텀 디멘션, 퍼널 분석을 위한 이벤트 설계의 단계까지 확장해 나아간다면 단순한 로그 수집을 넘어 의사결정을 돕는분석 환경을 만들 수 있다.

참고

https://github.com/codler/react-ga4/blob/HEAD/src/ga4.test.js

react-ga4/src/ga4.test.js at d50684824f5d155c772721d93ff2be7ea65767bf · codler/react-ga4

React Google Analytics 4. Contribute to codler/react-ga4 development by creating an account on GitHub.

github.com

https://www.npmjs.com/package/react-ga4

https://velog.io/@slight-snow/React.js-GA4Google-Analytics-API-%ED%98%B8%EC%B6%9C%ED%95%98%EA%B8%B0

[React.js] GA4(Google Analytics) - ②API 호출하기

React에서 GA4(Google Analytics) 보고서 API를 다루는 방법을 알아보고자 한다.

velog.io

Flutter Supabase 연결하기 (Feat. 공식문서)

흐성진 — Fri, 7 Nov 2025 16:54:13 +0900

주제선정

이번 글의 주제는 Flutter와 Supabase의 연동이다.
최근 진행 중인 새로운 사이드 프로젝트에 이 기술 스택을 직접 적용해보면서, 보다 효율적인 개발 환경을 구축하고자 하는 목적에서 이 주제를 선택했다.

기존에는 Firebase나 자체 서버를 활용한 경험이 있었지만, Supabase는 오픈소스 기반으로 백엔드 기능을 간편하게 구현할 수 있다는 점에서 흥미로웠다.

특히 Flutter와의 궁합이 좋아 실무 수준의 연동 과정을 익히기에 적합하다고 판단했다.

따라서 이번 포스팅을 통해 공식문서를 보면서 Flutter와 Supabase를 실제 프로젝트에 적용하면서 배우는 과정을 정리하고, 같은 주제를 공부하려는 개발자들에게 도움이 되는 자료를 만들어보고자 한다.

아래의 공식문서를 따라서 작성할 예정이다.

https://supabase.com/docs/guides/getting-started/quickstarts/flutter

Use Supabase with Flutter | Supabase Docs

Learn how to create a Supabase project, add some sample data to your database, and query the data from a Flutter app.

supabase.com

Supabase

Supabase 홈페이지

Supabase | The Postgres Development Platform.

Build production-grade applications with a Postgres database, Authentication, instant APIs, Realtime, Functions, Storage and Vector embeddings. Start for free.

supabase.com

공식홈페이지에 접속해서 회원가입을 진행해 준 다음, 프로젝트를 만들어 준다.

공식문서를 따라 들어가보면 다음과 같이 테이블을 만들라고 나와있다.

사이드 탭에보면 Table Editor 와 SQL Editor 를 볼 수 있는데 UI적으로 만드냐, 코드로 만드냐의 차이다.

예제에서는는 SQL 코드를 제공해 주기 때문에 그대로 사용해보겠다.

-- Create the table
create table instruments (
  id bigint primary key generated always as identity,
  name text not null
);
-- Insert some sample data into the table
insert into instruments (name)
values
  ('violin'),
  ('viola'),
  ('cello');

alter table instruments enable row level security;

다음 이미지와 같이 SQL 코드를 넣어주게 되면 테이블이 정상적으로 들어가 있는걸 볼 수 있다.

RLS 정책을 추가해서 테이블의 데이터를 공개적으로 읽을 수 있도록 설정또한 SQL Editor 를 통해서 진행해 준다.

create policy "public can read instruments"
on public.instruments
for select to anon
using (true);

Flutter 설정

Flutter 에서 Supabase 를 사용하려면 라이브러리의 설치가 필요하다.

https://pub.dev/packages/supabase_flutter

supabase_flutter | Flutter package

Flutter integration for Supabase. This package makes it simple for developers to build secure and scalable products.

pub.dev

해당 라이브러리를 설치해주도록 하자

flutter pub add supabase_flutter

설치가 완료되었으면 이제 main 부분에 url, annoKey 를 사용해줘야 되는데

해당 키값과 같은 민감한 정보는 .env에 등록해서 사용해준다.

키 등록이 완료 되었으면

main 부분에서 초기화를 진행 한 다음, URL과 키값을 불러와준다.

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await dotenv.load(fileName: ".env");

  await Supabase.initialize(
    url: dotenv.env['SUPABASE_URL']!,
    anonKey: dotenv.env['SUPABASE_ANON_KEY']!,
  );
  runApp(const MyApp());
}

정상적으로 등록되었다면 다음과 같은 메시지가 출력된다

데이터 가져오기

아래 코드와 같이 FutureBuilder를 사용해서 데이터를 가져올 수 있다.

데이터를 가져올때 기존에 가져온 테이블 명을 명시해 주고 그 뒤에는 여러 옵션들이 이 있는데

주요하게 사용할건 select, stream 이 주요하게 사용 될 것이다.

class HomePage extends StatefulWidget {
  const HomePage({super.key});
  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  final _future = Supabase.instance.client.from('instruments').select();
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: FutureBuilder(
        future: _future,
        builder: (context, snapshot) {
          if (!snapshot.hasData) {
            return const Center(child: CircularProgressIndicator());
          }
          final instruments = snapshot.data!;
          return ListView.builder(
            itemCount: instruments.length,
            itemBuilder: ((context, index) {
              final instrument = instruments[index];
              return ListTile(
                title: Text(instrument['name']),
              );
            }),
          );
        },
      ),
    );
  }
}

아래 코드를 실행시켜보면 다음과 같이 학기의 이름들을 가져올 수있다.

테스트를 위해 악기 하나를 더 추가해보고 가져오면

추가된 데이터 또한 정상적으로 불러와 지는 걸 볼 수 있다.

결론

우선 기초적인 Supabase 연결하는 방법에 대해서 공식문서를 보고 한번 따라해봤다.

아직 Supabase 의 기능을 제대로 쓰지는 않았지만, 앞으로 사이드 프로젝트를 진행하면서,

추가되는 내용에 대해서는 별도로 공부 후 작성할 예정이다.

React에서 이미지와 파일 관리 public vs. src/assets

흐성진 — Fri, 29 Aug 2025 20:04:02 +0900

들어가기

React를 처음 공부하면서 프로젝트를 만들었을때 생긴 의문점이였다.

vite.svg 파일은 public에 들어가있고 react.svg 파일은 src/assets 에 위치해 있었다.

그래서 이번에는 해당 내용에 대해서 개념적으로 공부하면서 정리해보고자 한다.

public 폴더의 특징

public 에서는 정적 파일을 다루게 된다.

직접 URL 접근

예를 들어 처음 react 프로젝트를 만들었을때를 가정해보자

App.tsx 파일에서 다음과 같이 불러오게 된다.

// 실제 코드에선 import 로 파일을 넣어준 다음 src={viteLogo} 를 사용
// 아래 코드에선 풀어 쓴 내용

<img src="/vite.svg" className="logo" alt="Vite logo" />

이렇게 사용하게 되면 다음과 같이 직접적인 URL을 통해서 접근할 수 있다.

경로는 프로젝트 루트 / 를 기준으로 한다.

빌드 후에 /vite.svg 같은 형태로 접근이 가능하다

빌드 최적화와 무관

실제로 빌드를 해보면 dist 폴더 안에 public 폴더에서의 vite.svg파일은 다음과 같이 나타내게 된다.

이렇게 직접적으로 파일이 적용되는 이유는 public 폴더에 넣은 파일은 Webpack/Vite 에 의해 관리 되지 않고 원본 자체가 복사되기 때문이다.

즉, 이말은

압축/ 최적화/ 해싱 이 적용되지 않는다.
파일이 수정되면 캐싱 문제를 피하기 위해 직접 파일명을 바꾸거나 쿼리스트링을 붙여야 한다.
경로가 잘못되거나 파일이 없는 경우 컴파일 에러는 발생하지 않고 404 에러만 발생하게된다.

필수 파일의 집합

favicon, mainfest, robots.txt, 오픈그래프 이미지 등 애플리케이션 동작이나 SEO에 꼭 필요한 파일을 둔다.

빌드를 할때 코드에서 import 하지 않아도 되며 단순하게 경로만 명시하면 끝이다.

보안에 주의

처음에 봤듯이 URL을 통해서 접근이 가능하다.

따라서 누구나 접근 가능한 공개 리소스만 두어야 한다.

민감한 문서, 인증서, API key 등은 절대 두지 않는다.
외부에 노출되어도 상관없는 파일만 넣는다

src/assets 폴더의 특징

import 방식의 관리

src/assets 폴더의 파일은 JS/TS 코드에서 import 형식으로 불러오게 된다.

import reactLogo from "./assets/react.svg";

<img src={reactLogo} className="logo react" alt="React logo" />

즉 직접 URL 로 접근은 불가능하고 반드시 import를 거쳐야 한다.

자동 최적화

빌드 도구(Webpack/VIte) 등 다음과 같은 최적화를 자동으로 적용한다.

파일 해싱(content hash) -> 캐싱 문제 방지
압축 및 용량 최적화
중복 제거
사용하지 않는 리소스 제거(Tree Shaking)

직접 URL접근의 불가

public과는 다르게 직접적인 URL을 통해서 접근이 불가능하고, 코드 내에서 import를 거쳐야 사용이 가능하다.

보안 및 역할 분리

비공개 리소스, 외부에 노출되면 안되는 파일 등도 안전하게 관리 할 수 있다.

구조화된 관리

프로젝트에 맞춰 assets/images/, assets/icons/ 등 세분화 하여 관리하면 유지보수성이 높아지고 재사용성이 높아지게 된다.

언제 뭘 써야되는걸까?

public은 외부 접근이 필요하고, 최적화가 불필요한 정적 파일(favicon, robots.txt, 큰 동영상, 3rd-paty 스크립트 등)

assets는 앱 내부에서 참조하며 최적화가 필요한 리소스 (아이콘, UI 이미지, svg 컴포넌트 등)

구분	public	src/assets
접근 방식	직접 URL(/vite.svg)	import 이후 사용
빌드 최적화	⛔ 없음 (원본 복사)	✅ 있음(해싱, 압축, 최적화)
캐싱	파일명 고정	content hash 자동 적용
보안	누구나 URL을 통해 접근 가능	코드 내부에서만 접근 가능
권장 사용	favicon, mainfest, robots.txt	UI리소스, 아이콘, 이미지

참조

https://whales.tistory.com/95

React에서 이미지(images) 경로 설정 방법

React에서 이미지를 사용해야 할 때 해당 이미지가 public폴더에 있는지 src폴더에 있는지, 또는 jsx파일에서 사용하는지 css에서 사용하는지에 따라 경로 설정하는 방법이 달라 처음 경로를 설정할

whales.tistory.com

https://ttaerrim.tistory.com/62

정적 에셋은 왜 src에서 관리하는 것이 좋을까?

이번 포스팅에서는 React + Vite 환경에서 정적 에셋을 public과 src 디렉토리에서 관리한 경험을 살펴보고 스스로 도출한 결론을 설명해 보려고 합니다. 6주 동안 진행된 morak 프로젝트에서는 정적 에

ttaerrim.tistory.com

Vite 기반 React 프로젝트에서 Path Alias 설정하기

흐성진 — Wed, 9 Jul 2025 18:14:14 +0900

패스트 캠퍼스 강의를 보면서 Vite 기반 React 프로젝트에서 Path Alias 설정하는 부분에 대해서 조금 다른 부분이 있어 해당 부분에 대해서 작성해보려고 한다.

Path Alias 는 왜 사용하는가?

Path Alias 는 프로젝트 내부에서 특정 경로를 별칭(alias) 를 설정하여 import 하게 해주는 기능이다.

만약 내가 import 해야되는 파일이 src/pages/main/lui/MainPage.tsx 파일이라고 가정해보자

그러면 기존의 방법론으론 경우에 따라 다르지만 상대경로 또는 절대경로를 사용하게 된다 그러면 다음과 같이 가독성이 떨어지는 문제가 발생한다.

import { MainPage } from "../pages/main-page/ui/MainPage";

근데 Path Alias 를 사용하게 되면 다음과 같이 사용이 가능하다

import { MainPage } from "@pages/main-page/ui/MainPage";

물론 Path Alias 를 어떻게 설정하느냐에 따라서 다음과 같이 간결하게 만들수도 있다.

import { MainPage } from "@ui/MainPage";

Vite에서 Path Alias 설정하기

Path Alias 를 하기위해서는 vite.config.ts, tsconfig.app.json 에서 수정을 진행해줘야한다

vite.config.ts 설정하기

typescript 상에서 path 부분에서 타입 오류가 발생할 수 있다.

이때는 다음 패키지를 설치해 주자

# npm 을 사용하는 경우
npm install -D @types/node

# yarn 을 사용하는경우
yarn add -D @types/node

그 후 다음과 같이 vite.config.ts 파일을 수정해 준다.

나 같은 경우에는 fsd 를 적용하고 각 레이어들을 설정해 주 었다.

import path from "path";

// https://vite.dev/config/
export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      "@app": path.resolve(__dirname, "./src/app"),
      "@pages": path.resolve(__dirname, "./src/pages"),
      "@widgets": path.resolve(__dirname, "./src/widgets"),
      "@features": path.resolve(__dirname, "./src/features"),
      "@entities": path.resolve(__dirname, "./src/entities"),
      "@shared": path.resolve(__dirname, "./src/shared"),
    },
  },
});

tsconfig.app.json 설정하기

이에 따라 tsconfig.app.json 파일도 설정을 해주어야 한다

baseUrl을 설정해주고 paths 에 각각의 레이어를 넣어주었다.

{
  "compilerOptions": {

    "baseUrl": ".",
    "paths": {
      "@app/*": ["src/app/*"],
      "@pages/*": ["src/pages/*"],
      "@widgets/*": ["src/widgets/*"],
      "@features/*": ["src/features/*"],
      "@entities/*": ["src/entities/*"],
      "@shared/*": ["src/shared/*"]
    },
  },
}

Path Alias 사용하기

// Path Alias 설정 전
import { MainPage } from "../pages/main-page";
import { cn } from "../../shared/lib/utils";

// Path Alias 설정 후
import { MainPage } from "@pages/main-page"
import { cn } from "@shared/lib/utils";

편하고 쉬운 방법(vite-tsconfig-paths)

위와 같이 설정해도 되지만 Path Alias 에 추가를 할때마다 vite.config, tsconfig.app 두가지 파일을 수정해 줘야 하는 귀찮음이 발생한다.

이를 해결하기 위해 vite 패키지 중에 vite-tsconfig-paths 를 사용하면 tsconfig만 수정해도 vite 번들에도 동시에 설정되도록 할 수 있다.

패키지 설치

# npm 사용시
npm i vite-tsconfig-paths

# yarn 사용시
yarn add vite-tsconfig-paths

vite.config.ts 설정하기

import tsconfigPaths from 'vite-tsconfig-paths';

// https://vite.dev/config/
export default defineConfig({
  plugins: [react(), tailwindcss(), tsconfigPaths()],
});

참고

https://bluemiv.tistory.com/114

Vite기반 React 프로젝트에서 Path Aliasing 설정하기

React 프로젝트에서 Path Aliasing을 설정하면, 복잡하고 긴 상대 경로 대신 짧고 명확한 경로로 모듈을 import할 수 있습니다. 본 글에서는 Path Aliasing을 설정하는 방법에 대해 설명합니다. Path Aliasing

bluemiv.tistory.com

React + Vite + TypeScript + Tailwind CSS(4.0 이상) 설정 방법

흐성진 — Fri, 4 Jul 2025 18:44:52 +0900

초보 React 개발자의 세팅 방법이다.

사실 기존에 정리된 글은 많은데 Tawilwind CSS 가 4.0 이상 버전에서 기존의 설치 방법과는 다른 부분이 있어 해당 내용에 대해서 정리하려고한다.

1. React + Vite + TypeScript 프로젝트 생성

npm create vite@latest react-templete

다음의 명령어를 치고 아래 이미지와 같이 따라하면 된다

React를 사용하므로 React 설정

TypeScript 설정

이렇게하면 React + Vite + TypeScript 의 설정은 끝이다.

2. Tailwind CSS 설치

위에서 말했듯이 해당 내용은 4.0 이상 버전의 Tailwind CSS 설치에 대해서 다룬다.

크게 다른건 없는데 설치해야되는 라이브러리, 설정 내용들의 차이가 있다.

프로젝트로 이동해서 해당 명령어를 통해서 설치해주면 된다.

npm install -D tailwindcss@latest @tailwindcss/vite

3. Tailwind CSS 적용을 위한 CSS파일 생성 및 설정

'src/index.css' 파일에서 해당 내용을 import 해주면 된다

@import "tailwindcss";

기존에는 @tailwind base; @tailwind components; @tailwind utilities 까지 사용해줘야 됐지만 해당 내용들이 사라지고 한줄로 import하면 된다.

4. Vite 설정 파일(vite.config.ts) 수정

아래 코드와 같이 Tailwind 플러그인을 추가 해주면 된다.

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

// https://vite.dev/config/
export default defineConfig({
  plugins: [react(), tailwindcss()],
});

여기서 주의해야 될 점은 플러그인 배열안에 tailwindcss() 를 반드시 추가해야 정상 작동한다.

5. Tailwind CSS 클래스 적용 확인

'src/main.tsx' 에서 방금 적용한 'index.css' 를 import한다

import './index.css'

그다음 'App.tsx' 파일에서 Tailwind CSS 가 정상 작동되는지 확인하려면

import "./App.css";

function App() {
  return (
    <h1 className="text-4xl font-bold text-blue-600">Hello Tailwind CSS</h1>
  );
}

export default App;

다음과 같이 Tailwind CSS 문법을 적용해보면 된다.

6. 개발 서버 실행

npm run dev

를 통해서 로컬에서 실행시켜보면

다음과 같은 결과를 얻을 수 있다 text-blue-600 의 컬러의 텍스트를 확인할 수 있다.

7. 추가 적용 사항

Tailwind CSS 4.0 이상의 버전부터는 기존의 tailwind.config.js 와 postcss.config.js 파일이 필수가 아니라고 한다.

기존에는 해당 명령어를 통해서 파일을 생성했지만

npx tailwindcss init -p

이제는 사용할 필요없이

index.css 파일 내부에서 직접 커스텀이 가능하다

@import "tailwindcss";

@theme {
  --color-primary: hsl(220, 90%, 56%);
  --color-secondary: hsl(340, 82%, 52%);
  --font-sans: "Inter", sans-serif;
}

/* 필요에 따라 @layer로 커스텀 유틸리티 추가 가능 */
@layer utilities {
  .btn-primary {
    @apply bg-primary text-white font-bold py-2 px-4 rounded;
  }
}

코드

https://github.com/Hsungjin/React/tree/main/personal/react-ts-tailwind-templete

React/personal/react-ts-tailwind-templete at main · Hsungjin/React

Contribute to Hsungjin/React development by creating an account on GitHub.

github.com

참조

https://medium.com/@npguapo/installation-of-tailwind-vite-react-javascript-or-typescript-ec1abdfa56b2

Installation of tailwind 4.0 + vite (react + javascript or typescript)

in cmd, navigate to the folder where you want to start the project and enter the command

medium.com

[JS] async/await VS Promise VS Callback

흐성진 — Mon, 26 May 2025 21:20:39 +0900

서론

이번에 React를 공부하면서 공부해야될 개념이 있었다.

자바스크립트 에서 비동기 처리 방식의 종류와 각 역할에 따라 언제 사용해야 좋을지에 대해서다.

강의를 들으면서 어떨때는 Callback 또 어떨때는 Promise 또 어떨때는 async/await을 사용하는 것이다.

Flutter 를 사용하면서는 Future, async, await, Stream 만 사용해왔었는데 JavaScript 에서의 비동기 처리를 하는 방법들이 각각 어떤 상황에서 사용해야 효율적인 프로그래밍이 될지에 대해서 알아볼 필요가 있다고 생각해서 이에 대해 정리해보려고 한다.

- 비동기 프로그래밍에 대한 예시

2025.01.31 - [ Flutter] - Flutter 에서의 비동기 프로그래밍 Future, async/await

Flutter 에서의 비동기 프로그래밍 Future, async/await

맨 처음 iOS를 공부하면서 가장 어렵게 느껴졌던 개념이 비동기 프로그래밍이었다.내용만 듣고 이걸 왜 쓰는 거지?라는 의문이 들어서 대충 흘려보냈다가 프로젝트에 들어가면서 그 중요성에 대

sj-d.tistory.com

자바스크립트의 비동기 처리

자바스크립트에서 비동기 처리는 웹 개발에서의 필수적인 요소이다.

서버에서 데이터를 가져오거나, 파일을 읽거나, 타이머를 설정하는 등의 작업은 모두 비동기적으로 처리하게 된다. 이렇게 비동기 작업을 효율적으로 다루기 위해서 자바스크립트에서는 세가지 주요 방식 (Callback, Promise, async/await)을 제공한다.

그리고 자바스크립트는 싱글 스레드 언어로 한번에 하나의 작업만 수행할 수 있다. 하지만 웹 애플리케이션은 여러 작업을 동시에 처리해야 하는 경우가 많다. 예를들어 사용자의 입력을 받으면서 동시에 서버에서 데이터를 가져와야 할 때 비동기 처리가 필요하게 된다. 이러한 비동기 처리 작업을 효율적으로 관리하기 위해 Callback, Promise, async/awit이 등장했다.

Callback(콜백 함수)

기본 개념

콜백 함수는 다른 함수에 인자로 전달되어 특정 작업이 완료 된 후에 호출되는 함수이다. 결과적으로 "너는 나중에 호출할게" 라고 의미할 수 있다.

function greet(name, callback) {
  console.log(`Hello, ${name}!`);
  callback();
}

function sayGoodbye() {
  console.log("Goodbye!");
}

greet("황성진", sayGoodbye);

// 출력
// Hello, 황성진!
// Goodbye!

비동기 처리 예제

콜백 함수는 비동지 작업에서 특히 유용하다

function fetchData(callback) {
  setTimeout(function() {
    const data = { id: 1, message: "Hello, world!" };
    callback(data);
  }, 2000);
}

function displayData(data) {
  console.log("데이터 받기 완료 :", data);
}

fetchData(displayData);
// 2초 후 출력: 데이터 받기 완료 : { id: 1, message: 'Hello, world!' }

장점

간단하고 이해하기가 쉽다
모든 브라우저에서 지원된다
특정 이벤트가 발생했을때 원하는 기능을 실행항 수 있다

단점

무한 콜백 지옥의 발생 가능성
에러처리가 복잡하다
가독성이 떨어진다

Callback Hell(콜백 지옥)

콜백 함수가 중첩되면서 코드의 가독성이 크게 떨어지는 현상을 말한다.

아래 이미지가 가장 잘 표한한 예시라고 생각된다.

무한 콜백지옥

Promise(프로미스)

Promise는 비동기 작업의 최종 완료 혹은 실패와 그 결과값을 나타내는 객체이다.

Promise가 생설될때 꼭 결과를 알 수 없는 작업의 최종 결과값을 나타낸다.

Promise는 세가지 상태중 하나를 가진다

대기(Pending) : 초기 상태, 이행되거나 거부되지 않은 상태
이행(Fulfilled) : 연산이 성공적으로 완료됨
거부(Rejected) : 연산이 실패함

let myPromise = new Promise(function(resolve, reject) {
  // 비동기 작업 수행
  setTimeout(() => {
    const success = true;
    if (success) {
      resolve("성공했습니다!"); // 성공 시 resolve 호출
    } else {
      reject("실패했습니다."); // 실패 시 reject 호출
    }
  }, 2000);
});

// 프로미스 소비
myPromise
  .then(result => console.log(result))   // 성공 시 실행
  .catch(error => console.log(error));  // 실패 시 실행

Promise Chaining(프로미스 체이닝)

Promise의 큰 장점 중 하나는 여러 비동기 작업을 연속적으로 처리할 수 있는 체이닝 기능이다.

function stepOne(value) {
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log(value);
      resolve();
    }, 3000);
  });
}

function stepTwo(value) {
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log(value);
      resolve();
    }, 2000);
  });
}

function stepThree(value) {
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log(value);
      resolve();
    }, 1000);
  });
}

// 프로미스 체이닝으로 순차적 실행
stepOne(1)
  .then(() => stepTwo(2))
  .then(() => stepThree(3))
  .then(() => {
    console.log("모든 단계 완료");
  });

장점

콜백 지옥을 해결하여 코드의 가독성을 향상 시킨다
체이닝을 통해 연속적인 비동기 처리가 용이함
catch 메서드를 통해서 오류에 대한 처리가 쉬움
여러 비동기 작업을 병렬로 처리 가능 (Promise.all, Promise.race 등)

단점

ES6 이전 브라우저에서는 polyfill 이 필요
코드가 여전히 복잡할 수 있음
조건부 로직 처리가 복잡함

Async/Await

가장 친숙한 개념이다.

Async/Await은 ES2017(ES8)에서 도입된 문법으로, Promise를 더욱 쉽게 사용할 수 있게 해주는 특별한 문법이다.

Async/Awit을 사용하면 비동기 코드를 마치 동기 코드처럼 작성 할 수 있다.

async 함수는 항상 Promise를 반환한다
await 은 Promise 가 처리될때 까지 함수 실행을 일시 중단한다

async function fetchUserData() {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/users/1');
    const userData = await response.json();
    console.log(userData);
    return userData;
  } catch (error) {
    console.error('유저정보 받아오기 오류', error);
    throw error;
  }
}

// 함수 호출
fetchUserData()
  .then(data => console.log('유저정보:', data))
  .catch(error => console.error('에러발생:', error));

Prmoise 와 Async/Await 의 비교

// Promise
fetch('https://jsonplaceholder.typicode.com/todos/1')
  .then(response => response.json())
  .then(json => console.log(json))
  .catch(error => console.log(error));

// Async/Await
async function fetchTodo() {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/todos/1');
    const json = await response.json();
    console.log(json);
  } catch (error) {
    console.log(error);
  }
}

fetchTodo();

장점

코드의 가독성 향상
직관적인 오류 처리(try-catch 구문 사용)
디버깅이 용이함
조건부 로직 처리가 쉬움

단점

ES2017 이전의 브라우저에서는 트랜스파일러 필요
병렬 처리 시 추가 작업 필요
await은 반드시 async 함수 구문내에서만 사용 가능

결론

자바스크립트에서 비동기 처리는 Callback, Promise, Async/Await 세 가지 방식으로 구현할 수 있다.

각 방식은 고유한 장단점을 가지고 있으며 상황에 따라 적절한 방법을 선택하는 것이 좋다.

Callback은 가장 기본적인 방식이지만 코드가 복잡해질 수록 가독성이 떨어지는 콜백 지옥 문제가 발생할 수 있다.

Promise는 콜백 지옥 문제를 해결하고 체이닝을 통해 연속적인 비동기 작업이 가능하지만 여전히 코드가 복잡해 질 수 있다.

Async/Await은 Promise 기반으로 동작하면서 동기 코드와 유사한 구조로 작성할 수 있어 가독성이 좋고 오류 처리가 직관적이다.

이렇게 현재 자바스크립트 개발에서는 Async/Await, Promise 가 주로 사용되며, 특히 Async/Await은 가독성과 오류 처리의 용이성으로 인해 많이선호된다(나도 제일 편해서 좋아한다) 하지만 모든 상황에 맞는 최고의 방식 은 존재할 수 없듯이 여러 방법론에 따라 다방면에서 고민하면서 항상 차선책을 찾으려 노력해야 된다고 생각한다.

이것은 UI 오류인가요? 아닙니다!(Feat. 서브픽셀 렌더링)

흐성진 — Mon, 12 May 2025 19:11:52 +0900

들어가기

회사에서 사용하는 업무툴중에 네이버 웍스 가 있다.

문득 웍스의 UI 를 바라보았는데

1:1 에서 왼쪽의 1과 오른쪽의 1이 다르다는 느낌을 받았다.(지금 보니 티스토리 에디터도 동일하게 미세하게 다르다)

그래서 캡쳐를 해서 확대를 해보았다

픽셀 단위로 바라보았을때 미묘하게 다르다는 느낌을 받았다.

나는 당연히 이건 UI 적으로 오류가 발생했다고 생각했다.

그래서 웍스 팀에 문의 메일을 보냈다.

문의한 답변에 대한 내용이다. 픽셀 차이 없이 동일한 상태라고 한다.

그러면 이런 현상은 왜 발생하는걸까? 라는 의문이 들었다.

서브픽셀 렌더링

LCD 화면에서 하나의 픽셀이 실제로는 세개의 서브픽셀(빨강, 초록, 파랑)로 구성되어 있다. 서브픽셀 렌더링은 이러한 구조를 활용하여 실질적으로 해상도를 높이는 기술이다.

https://en.wikipedia.org/wiki/Subpixel_rendering

일반적으로 LCD 화면의 각 픽셀은 RGB(빨강, 초록, 파랑) 세 개의 서브 픽셀로 이루어진다.
서브픽셀들은 서로 나란히 배치되어 있으며 대부분의 RGB 순서로 정렬되어 있다(일부는 BGR 도 있다고 한다)
인간의 눈은 이 세가지 색상이 섞여 하나의 색으로 보이도록 통합한다.

서브픽셀 렌더링은 이 개별 서브픽셀을 활용하여 더 정밀한 텍스트 렌더링 기능을 하게 한다. 일반적인 픽셀 단위 렌더링 보다 최대 3배 더 정밀하게 수평해상도를 제공할 수 있다고 하낟.

그래서 왜 생겨?

텍스트의 분수 픽셀 처리

이미지 에서 보이듯 차이는 분수 픽셀(fractional pixel)의 처리 방식 때문일 수도 있다고 한다

이것은 브라우저 마다 분수 픽셀을 다르게 처리 하기 때문에 발생한다고 하는데

1. 어떤 브라우저는 33.5px을 33px로 내림을 하는 경우도 있고

2. 어떤 브라우저는 서브픽셀 스케일로 렌더링 하는 경우도 있고

3. 일부 브라우저는 올바르게 반올림 하여 34px로 처리하는 경우도 있다.

이러한 차이는 특히 텍스트 렌더링에서 두드러지게 일어난다고 한다.

분스 픽셀을 사용할 때 Edge와 Firefox는 너비를 가장 가까운 전체 픽셀로 반올림 하는 반면, 다른 브라우저들은 정수 값만 사용하는 경향이 있다.

안티앨리어싱과 텍스트 렌더링

또 다른 가설은 안티앨리어싱 적용 여부와 방식의 차이 일 수 도 있다.

https://ko.wikipedia.org/wiki/%EC%9C%84%EC%8B%A0%ED%98%B8_%EC%A0%9C%EA%B1%B0

안티앨리어싱 기법

안티앨리어싱은 텍스트나 그래픽의 가장자리에 나타난 계단 현상을 감소시키는 기술이다.

서브픽셀 안티엘리어싱 - 서브픽셀 단위로 정밀하게 처리하여 텍스트를 더 선명하게 표현

기본 안티앨리어싱 - 픽셀 단위로 가장자리를 부드럽게 처리

CSS에서는 -webkit-font-smoothing: antialiaseed 와 같은 속성을 사용해서 폰트 렌더링 방식을 제어할 수 있다.

그 이유 (가설) - 사실 나는 다 틀림

1. 다른 렌더링 엔진의 사용 : 각 텍스트가 다른 렌더링 엔진을 사용하거나 스프트웨어에서 생성 되었을 수 있다.

2. 서브픽셀 렌더링 차이 : 하나는 서브픽셀 렌더링을 활용하고, 하나는 픽셀 렌더링을 사용했을 수 있다.

3. 안티앨리어싱 설정 차이 : 서로 다른 안티앨리어싱 방식이 적용되었을 가능성이 있다.

4. 폰트 힌팅차이 : 폰트 힌팅은 낮은 해상도에서 텍스트가 선명하게 보이도록 조정하는 기술인데 이 설정이 다를 수 있다.

결론

디지털 디스플레이에서 텍스트 렌더링은 서브픽셀 렌더링, 안티앨리어싱, 폰트 힝팅, 분수 픽셀 처리 등 다양한 방법론이 있고 어떻게 적용하는지에 따라서 유저에게 보여지는 부분이 미세하게 변동되는 경우도 있는 상황을 알게되었다.

결과론적으로 이런 방법도 알고있으면 추후에 도움이 되겠지만, 사실 결론은 모니터가 알아서 안티앨리어싱 을 해서 생기는 문제였다. 맥북화면으로 가져가게 되면 정상적인 픽셀료 표시되고 있었다.

결국 나는 무지에 의해서 와 신난다 네이버 오류 찾았다 라고 제보한 무지한 개발자가 되었다.

여러분은 이런 실수를 하지 않기를 바랍니다!

Flutter 클린아키텍처를 공부하면서 생긴 의문점 ~ ing

흐성진 — Fri, 18 Apr 2025 09:34:25 +0900

클린아키텍처 이해했어

이번 글은 초보 개발자가 클린아키텍처를 공부하면서 만나는 의문점들과 그에 대해서 조그맣게나마 공부하고 정리한 내용이다.

앞으로도 의문점들이 추가 될때 추가적으로 작성할 예정이다.

이번에 새로운 프로젝트를 시작하기에 앞서해보고 싶은 내용들을 정해봤다.

- 클린아키텍처 사용하기

- 작게나마 테스트코드 적용하기

이렇게 세가지의 조건을 가지고 클린 아키텍처에 대해서 공부하던 중에 생긴 의문점들과 그에 해당하는 답변들을 정리해보려고 한다.

1. DTO ~ Mapper ~ Model 이 효율적인가?

일단 지금까지의 내가 해오던 방식은 Model만 정의해서 사용했다.

이렇게 사용한 방법은 아래와 같이 옵셔널 하게 미리 정의해 놓고 필요한 값만 꺼내서 쓰는 방식이었다.

class User {
	String? id;
    String? name;
    String? email;
    String? phone;
}

근데 클린아키텍처를 공부하면서 지금까지의 개념과는 다르게 작용한 부분이라고 생각된다.

DTO 가 서버에서 받아온 데이터

Mapper 를 통해서

Model 이 된다 라는 개념이였다.

그래서 클로드에게 질문해 보았다.

아래는 질문에 대한 답변이다.

클린 아키텍처에서 DTO와 Model을 나누는 접근법에 대한 질문이시군요.

DTO와 Model을 분리하는 대신 Model에서 optional 값으로 처리하는 것이 더 편할 수 있다는 생각은 이해가 됩니다. 실제로 많은 개발자들이 이런 방식도 고려합니다. 각 접근법의 장단점을 살펴보겠습니다:

DTO와 Model을 분리했을 때의 장점:

관심사 분리: 네트워크 데이터 구조(DTO)와 앱 내부 로직 데이터 구조(Model)가 명확히 분리됩니다. API 변경 대응: 서버 API가 변경되더라도 내부 Model은 변경할 필요가 없고 Mapper만 수정하면 됩니다. 테스트 용이성: 비즈니스 로직을 테스트할 때 서버 응답 구조와 독립적으로 테스트할 수 있습니다. 도메인 중심 설계: 앱의 비즈니스 요구사항에 맞는 Model 설계가 가능합니다.

단일 Model에 optional 값으로 처리할 때 장점:

코드 간결성: 추가적인 매핑 코드가 필요 없어 코드량이 줄어듭니다. 개발 속도: 빠른 개발이 가능하고 DTO-Model 간 매핑 오류가 발생하지 않습니다. 유지보수 단순화: 변경 시 한 곳만 수정하면 되어 동기화 문제가 없습니다.

실제로는 프로젝트의 규모와 요구사항에 따라 적절한 접근법을 선택하는 것이 중요합니다:

작은 프로젝트나 빠른 프로토타이핑에서는 단일 Model에 optional 값을 사용하는 것이 개발 속도와 간결성 측면에서 더 효율적일 수 있습니다. 대규모 프로젝트나 장기 유지보수가 필요한 앱에서는 DTO-Model 분리가 확장성과 유지보수 측면에서 더 유리할 수 있습니다.

결국 트레이드오프의 문제이며, 현재 개발 중인 앱의 상황과 팀의 선호도에 따라 결정하는 것이 좋습니다. 중요한 것은 일관된 접근법을 유지하는 것입니다.

결론적으로는 선호도 차이 이게 내 눈에는 가장 크게 보인다.

일단은 정석의 방식대로 구현하고자 했을 때는 DTO, Model 을 분리해서 사용하는 것이 맞다고 생각된다.

그리고 최초의 목표 설정에 결국 테스트 코드 작성도 포함되어있고 무엇보다 정석을 알아야 편리함도 안다고 생각된다.

그래서 더욱더 정석의 방식대로 공부하려고 한다.

Flutter Debounce 와 Throttle

흐성진 — Fri, 21 Mar 2025 20:09:43 +0900

오류를 고치는 나

주제선정

시간이 조금 지났지만 한때 앱의 오류가 발생했던 적이 있다.

분명 유저가 채팅방을 생성하면 한번만 생성되어야 되는데 짧은 시간에 여러번 터치하게 되면 여러개의 방이 생기는 문제가 발생했다.

당시 요청사항

물론 유저가 악의적으로 해당 사항을 지속했다면 문제가 됐을것이다.

특히 내 도메인이 금융쪽이였으면 엄청난 큰 문제가 발생했을 것이다.

항상 만들면서 기능만 개발하기에 급급했던 내 잘못이였다.

그래서 이걸 해결하고자 했을때 여러 방법이 있었다.

처음에 내가 생각했던 방법은 bool 값을 넣어서 try catch final 로 진입자체를 막는방법 이였지만

조금 검색하다보니 Debounce 와 Throttle 이라는 라이브러리가 존재하는것 알았고 해당 라이브러리를 사용해서 고쳤다.

그래서 이번에는 해당 개념에 대해서 조금 더 자세히 공부하고, 라이브러리를 사용하는 것과 직접 구현하는 방법, 원래 생각했던 try catch finally의 사용 예제를 공유하고 비교해보려고 한다.

이번에는 라이브러리는 해당 라이브러리를 사용해서 작성하려고 한다.

https://pub.dev/packages/easy_debounce

easy_debounce | Dart package

An extremely easy-to-use method call debouncer package for Dart/Flutter.

pub.dev

우선 해당 에러를 가정하기 위해 간단하게 Hello Flutter 를 받아오는 API 를 만들어서 간단하게 dio 를 통해서 get 방식으로 가져와서 사용했다. ~~별거 아니긴 하지만 이래서 풀스택이 좋은건가 싶다.~~

Debounce

Debounce 의 개념

출처 : https://llu.is/throttle-and-debounce-visualized/

Debounce는 반복적인 이벤트의 실행을 지정된 이후 시간이 지난 후 이벤트가 실행된다.

Debounce 시간을 400ms 로 지정했다고 가정해보자

맨 처음 버튼을 정상적으로 한번 눌렀을 경우 400ms 이후 함수가 호출된다

그러면 빠르게 버튼을 10번 눌렀다고 가정해보자 어떻게 될까?

첫 버튼이 입력되고 다음 버튼의 입력을 지켜보고있다가 다음 입력이 일어나면 다시 400ms가 초기화 되면서

입력이 일어나지 않는 400ms 가 되면 함수를 한번 실행시켜준다.

예를 들어서 인터넷 쇼핑을할때 장바구니에 물건을 넣는다고 가정해보자

그러면 유저가 어떤 물건을 몇개를 담았는지 서버에 전송해야된다.

근데 유저가 버튼을 누를때마다 서버로 통신을하고 DB에 반영된다고 하면 상당히 비효율적일것이다.

이런 문제를 해결하기위해 등장했다고 한다.

또다른 예시로 검색 기능을 호출한다고 가정해보자

유저가 글자를 하나하나 입력할때마다 API 를 호출하면 "제주" 이 단어를 검색하는동안 "ㅈ" 에서 한번 "제" 에서 한번 이런식으로 호출이 증가하게 된다. 이것 방지하기위해서 디바운스를 적용한다고 한다.

Debounce 는 주로 검색창 입력, 유저 타이핑, 상품 구매 버튼 등에서 사용된다고 한다.

Debounce가 적용된 원을 직접 움직일 수 있다

https://rxmarbles.com/#debounce

Debounce 사용 예제

사실 라이브러리 사용이라 별로 어려운건 없다

  void _incrementDebounceCounter() {
    EasyDebounce.debounce('debounce', const Duration(milliseconds: 400), () {
      setState(() {
        _debouncecounter++;
      });
      callAPI('debounce');
    });
  }

Throttle

Throttle 의 개념

출처 : https://llu.is/throttle-and-debounce-visualized/

Throttle은 이벤트가 연속적으로 발생하면 일정한 시간동안 일어나게 되고 그 사이에 발생하는 다른 이벤트들은 무시하게 된다.

여기서 Debounce 와 다른점은 Throttle은 연속된 이벤트가 발생하더라도 타이머를 초기화하지 않는 것이다

만약 임계 시간을 400ms로 설정하고 390ms 에 버튼을 누르면 Debounce 와 같은경우는 타이머가 다시 400ms로 초기화 되겠지만 Throttle 은 타이머가 초기화 되지않고 발생한 이벤트에 대해서 무시하게 된다.

예를들어 스크롤 이벤트에 400ms의 Throttle 을 적용했다고 가정해보자.

Throttle을 통해서 스크롤의 끝에 도달하면 한번만 호출하게 된다

만약 Debounce 가 해당 기능에 적용되었다고 가정해보자

한번만 이벤트를 수행하게되면 큰 문제는 없이 작동된다 하지만 여러번 스크롤 이벤트를 호출한다면? 계속 400ms 의 타이머가 초기화되어 결국 함수가 호출되지 않을것이다.

참 같으면서도 많이 다르다.

Throttle 이 적용된 원을 직접 움직일 수 있다.

https://rxmarbles.com/#throttle

Throttle 사용 예제

  void _incrementThrottleCounter() {
    EasyThrottle.throttle('throttle', const Duration(milliseconds: 400), () {
      setState(() {
        _throttlecounter++;
      });
      callAPI('throttle');
    });
  }

호출 결과 비교

동영상 서비스가 종료되어 해당 콘텐츠를 재생할 수 없습니다.

확실히 결과를 놓고보니 비교가 편한것 같다.

눈에 잘 보이기 위해서 호출 관련 부분의 호출 횟수를 같이 넣어봤다

Debounce와 Throttle 직접 구현하기

Debounce와 Throttle을 찾아보다가 직접 구현하신 분도 봤다 해당 내용을 참고해서 작성해봤다

https://velog.io/@iwytbbtss/flutterthrottle-debounce-%EB%A7%8C%EB%93%A4%EA%B8%B0-%EA%B5%AC%ED%98%84-%EC%98%88%EC%A0%9C-by-Dart

[flutter]throttle, debounce 만들기, 구현 예제 by Dart

다른 언어로 프론트 개발을 해봤다면 이미 사용해봤거나 개념 정도는 익히고 있겠지만 flutter 그리고 Dart가 첫 개발 언어이신 분들을 위해 간단히 요약하자면throttle ➡️ 지정된 시간동안 연속

velog.io

Debounce

class Debounce {
  final Duration delay;
  Timer? _timer;
  Debounce({required this.delay});

  run(action) {
    // 이미 기다리고 있었다면 타이머를 초기화
    if (_timer != null) {
      _timer!.cancel();
    }
    // 지정된 시간이 지나면 action을 실행
    _timer = Timer(delay, action);
  }
}

Debounce debounce = Debounce(delay: const Duration(milliseconds: 400));

debounce.run(() {
  callAPI('Handmade debounce');
});

Throttle

class Throttle {
  final Duration delay;
  bool waiting = false;
  Timer? _timer;
  Throttle({required this.delay});

  void run(action) {
    // 타이머를 기다리지 않을 때만
    if (!waiting) {
      // action을 실행하고 이벤트를 기다림
      action();
      waiting = true;

      // 지정된 시간이 지나면 waiting을 풀어줌
      _timer = Timer(delay, () {
        waiting = false;
      });
    }
  }
}

Throttle throttle = Throttle(delay: const Duration(milliseconds: 400));

debounce.run(() {
  callAPI('Handmade debounce');
});

try catch finally 사용해보기

사실살 내 기준에서 제일 간편한 방법이다

bool 값 하나 넣어주고 try catch final 로 상태관리하기 이렇게하면 이전 이벤트가 종료 직전에는 api가 호출이 안되니까 말이다.

근데 지금 공부하면서 보니까 Debounce 나 Throttle 을 상황에 맞게 쓰는게 더 안전하게 보인다.

  bool isDoing = false;

  void _tryCatchFinally() async {
    try {
      if (isDoing) {
        return;
      }
      isDoing = true;
      await callAPI('try');
    } catch (e) {
      if (kDebugMode) {
        print(e);
      }
    } finally {
      isDoing = false;
    }
  }

코드

전체코드는 깃허브에서 확인할 수 있다.

https://github.com/Hsungjin/Flutter/tree/main/personal_study/debounce_throttle

Flutter/personal_study/debounce_throttle at main · Hsungjin/Flutter

Contribute to Hsungjin/Flutter development by creating an account on GitHub.

github.com

결론

동일하게 함수의 수행을 막는 방법이라고해도 참 여러가지 방법이 있는것 같다.

항상 개발을 하면서 느끼는게 최선의 선택은 없고 차선책을 강구해야되는것 같다.

그리고 해결 방법에 대해서 한번만 생각해보지 말고 꼭 여러번 생각하면서 검증의 시간도 필요 한 것 같다.

참조

https://velog.io/@iwytbbtss/flutterthrottle-debounce-%EB%A7%8C%EB%93%A4%EA%B8%B0-%EA%B5%AC%ED%98%84-%EC%98%88%EC%A0%9C-by-Dart

[flutter]throttle, debounce 만들기, 구현 예제 by Dart

velog.io

https://medium.com/@syaifakmal/debouncing-and-throttling-on-flutter-265d42eee8d9

Debouncing and Throttling in Flutter using flutter_debouncer 2.0.0

Ever encountered moments when your app’s responsiveness didn’t quite match your expectations? Imagine you’re typing a message or clicking a…

medium.com

Flutter 신용카드 예제 Like 카카오페이 2편

흐성진 — Wed, 5 Mar 2025 17:23:24 +0900

들어가기

2025.02.07 - [Flutter] - Flutter 신용카드 예제 Like 카카오페이 1편

Flutter 신용카드 예제 Like 카카오페이 1편

주제 선정 [Flutter] 그라데이션으로 만들어보는 광원 효과빛이 반사되는 효과는 어떻게 만들까?velog.io처음에 위의 글을 보고 애니메이션이 기깔난다고 생각을 하고있었다.문득 카카오페이를 들

sj-d.tistory.com

해당 글에 이어서 작성하는 내용이다.

우선 이전편에서 카드 생성, 토스카드 모양으로 그리기, 기타 애니메이션 등을 했었다.

이제 DB에 저장된 데이터를 받아와서 하단에서 카드를 보여주고, 상단영역에서는 카드 상세정보를 보여주면서

유저의 제스쳐에 따라서 카드의 각도가 변하면서 광원효과를 넣어보려고 한다.

카드 목록 보여주기

우선 카드 목록을 보여주기 위해서 데이터베이스에서 데이터를 가져와서 보여줘야한다.

데이터베이스 관련 내용은 저번에 다뤘기 때문에 생략하고

Carousel로 만들어서 상단에서 보여주려고 하려고한다.

https://pub.dev/packages/carousel_slider

carousel_slider | Flutter package

A carousel slider widget, support infinite scroll and custom child widget.

pub.dev

해당 라이브러리르 사용하면 carousel 을 쉽게 사용할 수 있다.

물론 공식지원하는 CarouselView 도 있고
https://api.flutter.dev/flutter/material/CarouselView-class.html

CarouselView class - material library - Dart API

A Material Design carousel widget. The CarouselView presents a scrollable list of items, each of which can dynamically change size based on the chosen layout. Material Design 3 introduced 4 carousel layouts: Multi-browse: This layout shows at least one lar

api.flutter.dev

이에 대응하는 방식인 PageView 도 있지만 세가지의 방법으로 구현해 봤을때 carousel_slider 가 가장 완성도가 높다고 판단하여 해당 라이브러리를 사용해서 진행하였다.

우선 우리가 스크롤 뷰를 사용하던, 탭바를 사용하던 컨트롤러를 지정해 주어야 한다.

carousel_slider 도 마찬가지로 컨트롤러를 만들어 주어야 한다.

final CarouselController controller = CarouselController(initialItem: 1);

다음은 CarouselSlider.builder 를 통해서 해당 _cards 의 리스트를 그려주도록 한다.

CarouselSlider

Stack(
  alignment: Alignment.center,
  children: [
    // Transform.translate를 사용하여 위치 조정
    Transform.translate(
      offset: const Offset(-75, 0), // x축으로 -75 픽셀 이동
      child: Container(
        height: 120,
        padding: const EdgeInsets.only(bottom: 20),
        child: CarouselSlider.builder(
          carouselController: _carouselController,
          itemCount: _cards.length,
          options: CarouselOptions(
            height: 100,
            viewportFraction: 0.8,
            enlargeCenterPage: true,
            enableInfiniteScroll: _cards.length > 1,
            initialPage: currentCardIndex,
            autoPlay: false,
            onPageChanged: (index, reason) {
              if (currentCardIndex != index) {
                setState(() {
                  currentCardIndex = index;
                });
              }
            },
            clipBehavior: Clip.none,
            padEnds: true,
            pageSnapping: true,
            disableCenter: false,
            enlargeStrategy: CenterPageEnlargeStrategy.scale,
          ),
          itemBuilder: (context, index, realIndex) {
            // 카드 색상 가져오기
            final cardColor = _getColorFromDynamic(_cards[index]['card_color']);
            
            return GestureDetector(
              onTap: () => _selectCard(index),
              child: CustomPaint(
                painter: CardPainter(
                  cardWidth: 150,
                  cardHeight: 90,
                  cardColor: currentCardIndex == index
                      ? cardColor
                      : cardColor.withValues(alpha: 0.5),
                ),
              ),
            );
          },
        ),
      ),
    ),
  ],
),

생각보다 구현하면서 CarouselOption 에서 많은걸 지정할 수 있었는데

기본적인 정의는 아래와 같다.

https://github.com/serenader2014/flutter_carousel_slider/blob/master/lib/carousel_options.dart

flutter_carousel_slider/lib/carousel_options.dart at master · serenader2014/flutter_carousel_slider

A flutter carousel widget, support infinite scroll, and custom child widget. - serenader2014/flutter_carousel_slider

github.com

여기서 내가 사용한 부분은

height
- 높이
viewportFraction
- 각 페이지가 사용하는 비율(기본값이 0.8 이라 사실 선언 안해줘도됨)
enlargeCenterPage
- 현재 페이지를 더 크게 보여줌(기본값 false)
enableInfiniteScroll
- 캐러셀 자체 슬라이드가 무한 반복 되어야 하는지 혹은 길이가 제한되어야 하는지
initialPage
- 캐러셀이 생성될때 최초에 보여지는 화면
autoPlay
- 자동 재생 여부(만약 true로 사용시 autoPlayInterval, autoPlayAnimationDuration, autoPlayCurve 등과 같이 사용 가능)
onPageChanged
- 페이지가 변경되었을때의 동작
clipBehavior
- 페이지에 대한 clipBehavior(기본값 Clip.hardEdge)
padEnds
- 목록의 양끝에 패팅을 추가할지에 대한 여부
pageSnapping
- 페이지에 대해서 스냅을 사용할지의 여부 false로 놓게되면 스크롤을 자유롭게 가능
disableCenter
- Center 위젯을 비활성화 할지에 대한 여부
enlargeStrategy
- 현재 위치한 인덱스의 확대 방법으로 CenterPageEnlargeStrategy.scale , .height, .zoom 을 사용가능하다

그리고 왜 Transform.translate 로 이동시켰는지 의문이 들 수 있는데 이상하게 나는 카드를 가운대로 보내고 싶은데 시작점이 가운데가 되는 현상이 있었고 이걸 해결하고자 위치를 강제적으로 이동시켜서 사용했다.

그리고 카드의 색상 같은 경우 SQFlite 에서는 별도의 색상관련 데이터를 지정할수 없어 TEXT 형식으로 받았기 때문에 변환해서 카드의 색상을 넣어주어야 했다.

Carousel Indicator

SizedBox(
  height: 50,
  child: Row(
    mainAxisAlignment: MainAxisAlignment.center,
    children: _cards.asMap().entries.map((entry) {
      return GestureDetector(
        onTap: () => _selectCard(entry.key),
        child: Container(
          width: 8,
          height: 8,
          margin: const EdgeInsets.symmetric(horizontal: 4),
          decoration: BoxDecoration(
            shape: BoxShape.circle,
            color: currentCardIndex == entry.key
                ? Colors.white
                : Colors.white.withValues(alpha: 0.5),
          ),
        ),
      );
    }).toList(),
  ),
)

그리고 현재 탭의 위치에 대해서 인지를 시켜주기위해서 만들어주었다.

카드의 값에 따른 UI 구현

child: CustomPaint(
  painter: CardPainter(
    cardWidth: 300,
    cardHeight: 200,
    cardColor: _getColorFromDynamic(_cards[currentCardIndex]['card_color']),
  ),
  child: SizedBox(
    width: 300,
    height: 200,
    child: Stack(
      children: [
        // 카드 번호
        Positioned(
          top: 120,
          left: 20,
          child: Text(
            _cards[currentCardIndex]['card_number'] ?? '',
            style: const TextStyle(
              color: Colors.white,
              fontSize: 16,
              fontWeight: FontWeight.bold,
            ),
          ),
        ),
        // 카드 소유자 이름
        Positioned(
          top: 160,
          left: 20,
          child: Text(
            _cards[currentCardIndex]['card_name'] ?? '',
            style: const TextStyle(
              color: Colors.white,
              fontSize: 16,
              fontWeight: FontWeight.bold,
            ),
          ),
        ),
        // 카드 만료일
        Positioned(
          top: 160,
          right: 20,
          child: Text(
            _cards[currentCardIndex]['card_expiration_date'] ?? '',
            style: const TextStyle(
              color: Colors.white,
              fontSize: 16,
              fontWeight: FontWeight.bold,
            ),
          ),
        ),
      ],
    ),
  ),
),

현재 선택한 카드의 내용을 보여주기 위한 UI 이다.

기존에 1편에서 다뤘던 카드를 추가하는 부분이랑 큰 차이는 없으니 별다른 설명없이 넘어가겠다.

구현 결과는 다음과 같다.

드래그를 통해 움직이는 효과 주기

이렇게 카드를 슬라이드를 통해서 움직이게 만들어줬다.

그러면 이제 필요한건 내가 터치이벤트를 발생시켜서 드래그를 하면 그 방향으로 움직이는 부분을 만들어야 한다.

그러기 위해선

카드를 터치한다 -> 카드가 터치되었다는 신호를 받는다 -> 드래그를 하면 카드가 움직인다 -> 손을떼면 원래 위치로 돌아온다.

이렇게 구현해야 한다.

크게 어려운건 없고 카드 위젯 자체에 GestureDetector 로 감싸주고

이번에 처음 써보는 onPanStart, onPanUpdate, onPanEnd 를 사용했다.

해당 기능은 조이스틱과 같은 상황에서 많이 사용된다고 한다.

우선 onPanStart 를 통해서 드래그 이벤트가 일어날 준비를 한다

onPanStart: (_) {
	isCardTilting = true;
},

그다음 onPanUpdate 를 통해서 사용자의 드래그에 대해 업데이트 한다

onPanUpdate: (details) {
  _onPointerMove(details.localPosition, const Size(300, 200));
},

// 사용자의 터치 위치에 따라 기울기 값 조절
void _onPointerMove(Offset position, Size cardSize) {
  if (!isCardTilting) return;
  
  setState(() {
    // 카드 중심을 기준으로 기울기 계산
    final centerX = cardSize.width / 2;
    final centerY = cardSize.height / 2;
    
    // 터치 위치와 중심 간의 차이를 기반으로 기울기 계산
    tiltX = ((position.dy - centerY) / 10).clamp(-15.0, 15.0);
    tiltY = (-(position.dx - centerX) / 10).clamp(-15.0, 15.0);
  });
}

기울기 계산 로직은 사용자의 터치 위치와 카드 중심점 간의 거리를 기반으로 계산한다.

먼저 카드의 중심점을 계산해서 centerX, centerY 를 잡아주고,

tiltX 는 Y 축 방향의 터치 위치(position.dy)와 중심점 의 차이를 기반으로 계산된다. 여기서 -15도에서 15도로 제한한 이유는 사용자가 카드 위쪽을 터치하면 tiltX는 음즈가 되어 카드가 앞으로 기울어지고 아래쪽을 터치하면 양수가 뒤에 반대로 기울임을 주기 위함이다.

tiltY 는 X 축 방향의 터치 위치(position.dx)와 줌심점의 차이를 기반으로 계산된다. 여기서 Y는 - 를 사용한 이유는 직관적인 움직임을 위해서이다. 사용자가 카드의 오른쪽을 터치하면 음수가 되어 카드가 오른쪽으로 기울어지고 왼쪽을 터치하게되면 양수가 되어 카드가 왼쪽으로 기울어 지게 된다.

이렇게 계산된 tiltX 와 tiltY 값은 밑에 Matrix4에서 3D 회전에서 다시 사용하게 된다.

드래그가 종료되면 onPanEnd 를 통해서 다시 원래의 상태로 되돌린다.

onPanEnd: (_) => _resetTilt(),

// 손을 떼면 원래 위치로 돌아가는 애니메이션 적용
void _resetTilt() {
  isCardTilting = false;
  _animationController.forward(from: 0.0);
}

이전에 사용했던 Transform의 Martrix4 를 통해서 이동에 따른 원근감을 주면서 회전을 시켜준다.

child: Transform(
  transform: Matrix4.identity()
    ..setEntry(3, 2, 0.001) // 원근감 추가
    ..rotateX(tiltX * (pi / 180))
    ..rotateY(tiltY * (pi / 180)),

이렇게 사용하게 되면 사용자의 터치 드래그 이벤트를 받아오면서 카드를 회전시킬 수 있다.

원금감을 주기위해 Z축 방향으로 원근감을 추가해주고,

rotateX와 rotateY 메서드는 각각 X축과 Y축을 중심으로 회전 변환을 적용하기 위해서 pi / 180 을 곱해주게 되는데,

Martrix4는 라디안을 단위로 한다.

하지만 현재는 각도(degree)를 사용하기 떄문에 라디안(radian)으로 변환을 하기 위함이다.

움직임에 따라 광원 효과 주기

그럼 이제 해야되는건 움직임에 따라서 카드의 빛 반사를 만들어 줘야한다.

딱히 어려운건없고 Stack 에 Positioned 을 통해서 카드 위젯 위해 쌓아서 구현했다.

이전에 기울기를 통해 얻어오는 tilitX, tiltY 의 값을 통해서 opacity 를 조정하면서 만들어줬다.

opacity 값은 X축과 Y축 기울기의 절대값의 합(tiltX.abs() + tiltY.abs())를 30으로 나눈 값으로 설정했다.

이렇게 만들게 되면 카드가 더 많이 기울어 질수록 뚜렷하게 광원효과를 나타낼 수 있다.

그라데이션 자체의 시작을 왼쪽 상단 끝을 오른쪽 하단으로 줘서 왼쪽 상단에 광원이 있는것처럼 효과를 냈고 반투명한 흰색을 넣었다.

// 빛 반사 효과 (기울기에 따라 투명도 변경)
Positioned.fill(
  child: Opacity(
    opacity: (tiltX.abs() + tiltY.abs()) / 30,
    child: Container(
      decoration: BoxDecoration(
        gradient: LinearGradient(
          begin: Alignment.topLeft,
          end: Alignment.bottomRight,
          colors: [
            Colors.white.withValues(alpha: 0.7),
            Colors.transparent,
          ],
        ),
        borderRadius: BorderRadius.circular(12),
      ),
    ),
  ),
),

이렇게 사용하게되면 사용자의 드래그에 따라서 카드가 회전하면서 광원효과를 받을 수 있다.