Generate clients with appropriate type signatures Generate, validate, cache and mock in your frontend applications, based on your OpenAPI specification.

Orval은 단순히 API 호출 코드만 만드는 게 아니라, 프론트엔드 개발의 전 과정을 자동화하는 데 초점을 맞춘 도구입니다.

주요 기능:

    생성(Generate): OpenAPI 명세서를 바탕으로 TypeScript 클라이언트를 자동으로 만듭니다.

    검증(Validate): 입력값이나 응답값이 올바른지 확인하는 로직을 포함합니다.

    캐싱(Cache): **TanStack Query (React Query)**와 같은 라이브러리와 연동하여 데이터 캐싱 및 상태 관리를 쉽게 도와줍니다.

    모킹(Mock): 테스트를 위해 가짜 데이터(MSW 등)를 자동으로 생성해 줍니다.

한 줄 요약: API 호출부터 데이터 관리, 테스트용 가짜 데이터 생성까지 한 번에 해결하고 싶은 프로젝트에 적합합니다.

Hey API

OpenAPI to TypeScript in seconds. Generate production-ready SDKs and validators from your OpenAPI spec. Used by Vercel, OpenCode, and PayPal.

"몇 초 만에 OpenAPI를 TypeScript로"

Hey API는 빠르고 가벼우며, 현업에서 즉시 사용할 수 있는 수준의 견고한 코드를 생성하는 데 특화되어 있습니다.

주요 기능:

    프로덕션 준비(Production-ready): Vercel, PayPal 같은 대기업에서 사용할 정도로 안정적이고 최적화된 SDK(소프트웨어 개발 키트)를 생성합니다.

    검증기(Validators): OpenAPI 명세에 정의된 규칙대로 데이터가 들어오는지 체크하는 검증 로직을 만들어 줍니다.

    속도와 편의성: 복잡한 설정 없이도 몇 초 안에 TypeScript 환경에 맞는 코드를 뽑아냅니다.

급하게 만드시느라 DOM 가상화 부분을 안하셨나 생각해서 찾아보니 tanstack Virtural 라이브러리가 설치되어있었고 설정이 되어있었다.

하지만 무엇때문인지 적용되지 않고 있었다. useWindowVirtualizer이 아니라 다른것을 사용하고 계셔서 사용자가 screen한 영역만 렌더링 되는것이 아니라 그 이외에 영역도 렌더링이 진행되고 있었다.

해당 hook을 사용하고 나니 모든게 렌더링 되지 않아서 원인을 살펴보니 최소 height가 없어서 그랬다. 그래서 처음 list에 보이는 12개의 productCard 높이인 800px을 주었다.

그 결과 하얀화면이 보이고 약간이라도 스크롤해야 list가 보였다.

가상화 라이브러리는 대량의 데이터를 효율적으로 보여주지만, "보이는 영역만 그린다"는 대전제 때문에 뷰포트 계산이 1px이라도 어긋나면 사용자에게 '하얀 화면'을 보여주는 치명적인 단점이 있습니다.

최근 프로젝트에서 TanStack Virtual(v3)을 사용하며 겪은 초기 렌더링 흰 화면 이슈와 이를 해결하기 위해 6차에 걸쳐 진행한 최적화 기록을 공유합니다.

1. 문제 현상: "왜 살짝 스크롤해야 나타날까?"

모바일에서는 멀쩡한데, 데스크탑에서만 페이지 진입 시 목록이 비어 있다가 스크롤을 1px이라도 움직여야 상품이 나타나는 현상이 발생했습니다.

2. 원인 분석: 가상화 엔진의 '시차'와 '오판'

원인은 크게 세 가지였습니다.

- Window Scroll 인식 오류: 컨테이너가 아닌 윈도우 스크롤을 사용함에도 가상화 인스턴스가 초기 위치(scrollMargin)를 0으로 오판함.

- 레이아웃 시프트(Layout Shift): 데스크탑의 Sticky 카테고리 바가 접히거나 펼쳐질 때 컨테이너의 절대 위치가 변하지만, ResizeObserver는 이를 감지하지 못함.

- 렌더링 타이밍(Race Condition): React의 상태 업데이트와 TanStack Virtual 내부 캐시 갱신 사이에 미세한 시차가 발생하여 transform 값이 음수로 튀는 현상.

3. 해결 과정: 6단계의 최적화

1단계: useWindowVirtualizer 전환 및 initialRect 도입

윈도우 레벨 스크롤을 정확히 감지하도록 전환하고, SSR 환경에서 뷰포트 높이가 0으로 잡혀 아이템이 아예 안 그려지는 문제를 막기 위해 initialRect fallback(800px)을 설정했습니다.

2단계: State vs Ref의 갈등

scrollMargin을 useState로 관리하려 했으나, TanStack Virtual 내부의 virtualRow.start(캐시값)와 즉시 변하는 state 간의 타이밍 불일치로 리스트가 덜덜 떨리는 현상이 발생했습니다. 결국 Ref 기반 계산 + 강제 Re-render(Tick) 전략을 택했습니다.

3단계: useLayoutEffect로 Paint 전 스크롤 제어

카테고리 전환 시 useEffect를 쓰면 화면이 한 번 깜빡인 뒤 스크롤이 위로 올라갑니다. 이를 useLayoutEffect로 옮겨 브라우저가 화면을 그리기(Paint) 전에 스크롤 위치와 데이터를 동기적으로 교체했습니다.

4단계: transitionend 이벤트 활용

데스크탑 Sticky 바의 애니메이션(grid-template-rows)이 끝나는 시점을 감지하도록 리스너를 추가했습니다. 애니메이션으로 인해 컨테이너 위치가 밀려나면 scrollMargin을 재계산하고 가상화 엔진을 강제로 깨웠습니다.

5단계: 초기 마운트 'Tick' 트리거

가장 결정적인 해결책이었습니다. 초기 마운트 시 scrollMargin이 계산되어도 리렌더링이 없으면 엔진은 0을 기준으로 계산합니다. setScrollMarginTick을 통해 마운트 직후 강제로 한 번 더 그리도록 하여 '선 스크롤' 문제를 해결했습니다.

6단계: 브라우저 전용 initialRect 분리

브라우저 환경에서도 가짜 높이(800px)를 주입하면 첫 계산이 틀어질 수 있습니다. SSR에서만 fallback을 쓰고, 클라이언트에서는 실제 window.innerHeight를 사용하도록 수정하여 정확도를 높였습니다.

최종 결과물 (핵심 로직)

// scrollMargin 갱신 후 virtualizer 강제 재계산 로직
useLayoutEffect(() => {
  if (scrollMarginTick > 0) {
    // 1. 아이템 사이즈 캐시 초기화
    virtualizer.measure();
    // 2. 가상화 엔진의 calculateRange를 강제 호출하기 위해 scroll 이벤트 dispatch
    // (TanStack Virtual은 scroll/resize 이벤트에서만 계산을 수행하기 때문)
    window.dispatchEvent(new Event('scroll'));
  }
}, [scrollMarginTick]);

마치며: 잔존 이슈와 교훈

아직 overscan 기본값 설정이나 itemCount 의존성 최적화 같은 과제가 남아있지만, 이번 트러블슈팅을 통해 얻은 교훈은 명확합니다.

"가상화는 단순히 라이브러리를 쓰는 것이 아니라, 브라우저의 렌더링 사이클(Layout -> Paint -> Composite)과 엔진의 계산 주기를 동기화시키는 작업이다."

특히 TanStack Virtual처럼 성능을 위해 많은 것을 내부 캐시에 위임하는 라이브러리를 쓸 때는, '지금 리액트가 아는 값'과 '엔진이 아는 값'이 일치하는지를 항상 의심해야 합니다.

문제: 데스크탑 레이아웃 시프트로 인한 초기 흰 화면 및 스크롤 전 미출력.

해결:

    useWindowVirtualizer + scrollMargin Ref 관리.

    useLayoutEffect를 통한 동기적 위치 보정.

    transitionend 및 마운트 시점 강제 이벤트 디스패치.

결과: 모든 환경에서 깜빡임 없는 매끄러운 가상화 그리드 구현 완료.

  즉, 흐름이 이렇습니다:

  .env.production (PostHog 키 포함, 이미 커밋됨)       ↓   pnpm turbo run build (빌드 타임에 NEXT_PUBLIC_* 인라인)       ↓   Docker deploy 타겟 (빌드된 파일만 복사, 런타임 env 불필요)

  Reddit/Medium 글에서 말하는 문제는 런타임에 NEXT_PUBLIC_ 변수를 주입하려 할 때 발생하는 건데, 이 프로젝트는 빌드   타임에 .env.production에서 인라인하는 방식이라 해당되지 않습니다.

  .env.production에 PostHog 키가 이미 들어있으므로, 그대로 배포하면 됩니다.

참고:

• https://nextjs.org/docs/pages/guides/environment-variables#bundling-environment-variables-for-the-browser
• https://www.reddit.com/r/nextjs/comments/1gj7lry/next_public_env_vars_not_working_in_production/?tl=ko
• https://carbonable.medium.com/deploying-a-next-js-app-with-next-public-environment-variables-with-docker-using-fly-io-1c0bfb3d999c

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/frontend"
    target-branch: "main"
    schedule:
      interval: "weekly"
      day: "monday"
    open-pull-requests-limit: 10
    labels:
      - "dependencies"

  - package-ecosystem: "gradle"
    directory: "/backend"
    target-branch: "main"
    schedule:
      interval: "weekly"
      day: "monday"
    open-pull-requests-limit: 10
    labels:
      - "dependencies"

  - package-ecosystem: "github-actions"
    directory: "/"
    target-branch: "main"
    schedule:
      interval: "weekly"
      day: "monday"
    open-pull-requests-limit: 5
    labels:
      - "dependencies"

설정 설명:

• directory: /frontend - frontend 디렉토리의 npm 의존성 모니터링
• target-branch: main - Dependabot PR이 main 브랜치를 대상으로 생성됨
• schedule: 매주 월요일마다 자동으로 의존성 체크
• open-pull-requests-limit: 동시에 열 수 있는 PR의 최대 개수 10개
• labels: PR에 "dependencies" 라벨 자동 추가

1) async/await

params의 Type은 Promise이다.

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const slug = (await params).slug
  return <div>My Post: {slug}</div>
}

2) useParams

'use client'

import { useParams } from 'next/navigation'

export default function ExampleClientComponent() {
  const params = useParams<{ tag: string; item: string }>()

  // Route -> /shop/[tag]/[item]
  // URL -> /shop/shoes/nike-air-max-97
  // `params` -> { tag: 'shoes', item: 'nike-air-max-97' }
  console.log(params)

  return '...'
}

참고

• https://nextjs.org/docs/app/guides/upgrading/version-15#params--searchparams
• https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes#convention

수동으로 tailwind 설정파일을 만들라고 되어있었는데

import type { Config } from 'tailwindcss'

const config: Config = {
  content: [
    './pages/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
    './app/**/*.{js,ts,jsx,tsx}', // MDX 페이지 포함
  ],
  theme: {
    extend: {},
  },
  plugins: [
    require('@tailwindcss/typography'),
  ],
}

export default config

Tailwindcss v4 부터는 tailwind.config.js(ts) 파일이 사용되지 않는다!!

그래서 찾다가 NextJS(15.3.0) 에서 app/globals.css에서 @plugin을 이용하니 작동이 되었다.

@import 'tailwindcss';
@plugin '@tailwindcss/typography';

tailwindcss-v4 css-first-configuration

Instead of a tailwind.config.js file, you can configure all of your customizations directly in the CSS file where you import Tailwind, giving you one less file to worry about in your project:
tailwind.config.js 파일 대신 Tailwind를 가져오는 CSS 파일에서 모든 사용자 지정을 직접 구성할 수 있어 프로젝트에서 걱정할 파일이 하나 줄어듭니다:

The new CSS-first configuration lets you do just about everything you could do in your tailwind.config.js file, including configuring your design tokens, defining custom utilities and variants, and more
새로운 CSS 우선 설정을 통해 tailwind.config.js 파일에서 할 수 있는 거의 모든 작업을 수행할 수 있습니다. 여기에는 디자인 토큰 구성, 사용자 지정 유틸리티 및 변형 정의 등이 포함됩니다

참고사이트

• https://github.com/tailwindlabs/tailwindcss/discussions/13292
• https://www.reddit.com/r/tailwindcss/comments/1i1whrk/write_plugin_in_tailwind_40/

통계학의 피카소는 누구일까: 20세기 과학혁명을 이끈 통계학 영웅들의 이야기

Lady Tasting Tea : How Statistics Revolutionized Science in the Twentieth Century

칼 피어슨, 고셋, 피셔, 네이만, 이곤 피어슨, 콜모고로프, 튜키, 마할라노비스, 크레이머, 왈드, 코크란, 박스, 콕스, 튜키 등의 통계를 공부하다보면 한번 쯤은 봤을 이름들이 등장한다.

통계학자들이 이론을 만든 역사를 간략히 알 수 있어서 좋은 책이었다!!

불멸의 이론 베이즈 정리는 어떻게 250년 동안 불확실한 세상을 지배하였는가

The Theory That Would Not Die How Bayes' Rule Cracked the Enigma Code, Hunted Down Russian Submarines, and Emerged Triumphant from Two Centuries of

확률을 해석하는 두 가지 관점으로 빈도주의 학파 vs 베이즈학파로 나눌 수 있는 것 같다.

처음 베이즈 이론이 나온 것도 토마스 베이즈가 신의 존재를 증명으로 베이즈 이론이 시작되었다. The Naive Bayesian Algorithm-based Prisoner’s Dilemma Game Model 위의 학술자료를 읽어보면 빈도주의보다 베이즈 이론이 더 효과적이라는 생각이 든다.