웹 개발 데일리 브리핑 — 2026-11-16
Soshy··조회수 —

기준 시점: 2026-11-16 06:00 KST
조사 범위: 전일 2026-11-15 06:00 ~ 당일 2026-11-16 06:00 KST
추천 글 범위: 기준 시점 당시 최근 7일
1️⃣ 프론트엔드
이번 조사 범위에서 포함할 만한 주요 신규 발표를 확인하지 못했습니다.
React, Next.js, Vercel, Vue, Nuxt, Angular, Svelte, SvelteKit, Astro, Remix의 공식 블로그와 GitHub 릴리스 기록을 확인했다.
이번 기간에는 주요 프론트엔드 프레임워크의 새로운 안정 버전이나 중요한 렌더링 API의 정식 출시를 확인하지 못했다.
조사 과정에서 제외한 Next.js 16.5.0-canary.51
- 발표일: 2026-11-14 — GitHub 표시 시각 23:43, 시간대 미확인
- 버전: Next.js 16.5.0-canary.51
- 안정화 단계: Canary Pre-release
- 원문: https://github.com/vercel/next.js/releases/tag/v16.5.0-canary.51
Next.js의 공식 릴리스에서 16.5.0-canary.51을 확인했다.
이번 버전의 주요 변경은 Turbopack 내부 작업 관리와 관련된다.
구체적으로는 Keyed Refinement의 Reader 측에서 Owner Task를 해제하는 시점을 수정했다.
Turbopack은 파일과 모듈 사이의 의존성을 추적하고 필요한 계산 결과를 관리한다. 따라서 내부 작업의 소유권과 참조 관계를 정확하게 처리해야 한다.
하지만 이번 릴리스 노트에는 새로운 사용자 API, 설정 옵션 또는 정식 기능 추가가 명시되지 않았다. 빌드 시간과 메모리 사용량에 관한 Benchmark도 포함되지 않았다.
따라서 이번 변경을 새로운 프론트엔드 기능의 주요 출시로 선정하지 않았다.
특히 이전 브리핑에서 다룬 Next.js 16.5.0-canary.50의 Client Reference Manifest 압축, Turbopack Garbage Collection 기본 활성화, RSC Navigation 수정과는 별개의 후속 내부 변경이다.
또한 다른 주요 프레임워크에서 확인한 최근 릴리스도 조사 기간 이전에 공개된 항목이었다.
- Vue 3.6.0-rc.15: 11월 12일 공개된 Release Candidate
- Astro 7.4.12: 11월 13일 공개된 안정 패치
- SvelteKit 3.2.0: 11월 10일 공개
- Nuxt 4.6.4: 11월 2일 공개
- Vite 8.3.8: 11월 11일 공개
이번 기간에는 기존 발표를 새로운 소식으로 반복하지 않았다.
다만 프론트엔드 개발 도구에서는 의미 있는 변경이 확인됐다.
Biome 2.6.8은 JavaScript와 TypeScript뿐 아니라 Vue 컴포넌트에서 발생하는 비동기 상태 관리 오류를 찾아내는 새로운 Lint 규칙들을 추가했다.
이는 프론트엔드 프레임워크 자체의 변경이 아니므로 개발 도구 및 보안 섹션에서 다룬다.
2️⃣ 웹 플랫폼·브라우저
이번 조사 범위에서 포함할 만한 주요 신규 발표를 확인하지 못했습니다.
W3C, WHATWG, TC39, MDN, Chrome·Chromium, Firefox·Mozilla, WebKit·Safari의 공식 공개 자료와 JavaScript, TypeScript, CSS, 웹 성능 및 접근성 관련 정보를 조사했다.
이번 기간에 새로운 주요 웹 표준이 정식 채택됐거나 안정 브라우저에서 중요한 신규 API가 기본 제공되기 시작했다는 발표는 확인하지 못했다.
WebKit과 Chromium의 개발 기록에서는 지속적인 구현 변경이 이루어지고 있다. 하지만 개발 브랜치의 Commit과 실제 안정 브라우저의 기능 출시는 구분해야 한다.
예를 들어 브라우저 엔진이 새로운 CSS 기능을 구현했더라도 해당 기능이 실험 설정 뒤에 존재한다면 일반 웹사이트에서 바로 사용 가능한 안정 기능으로 취급할 수 없다.
또한 Living Standard의 문서 갱신 날짜만으로 새로운 기능이 출시됐다고 판단하지 않았다.
이번 조사에서는 주요 표준화 기구의 문서 갱신과 실제 브라우저 구현 상태를 함께 확인할 수 있는 중요한 신규 발표를 찾지 못했다.
Firefox 160의 WebTransport 변경, 기기 내 음성 인식과 보안 취약점 수정은 이전 브리핑에서 이미 다뤘으므로 반복하지 않았다.
이번 추천 글에서는 이미 제공되는 웹 플랫폼 기능을 실제 서비스에서 활용할 때 나타나는 문제를 다룬다.
특히 React View Transitions의 Suspense 실행 시점, CSS Transform의 이미지 재샘플링 문제, CSS Container Query Unit을 이용한 인쇄용 레이아웃 설계를 자세히 살펴본다.
3️⃣ 백엔드·인프라
이번 조사 범위에서 포함할 만한 주요 신규 발표를 확인하지 못했습니다.
Cloudflare, AWS, Google Cloud, Microsoft Azure의 주요 공식 발표와 서버리스·엣지 플랫폼, 데이터베이스, API 및 관련 인프라 변경 기록을 조사했다.
Cloudflare의 공식 Changelog에서 확인한 최신 주요 제품 발표는 11월 13일에 집중돼 있었다.
- Workers 및 Durable Objects의 지출 상한
- Browser Run의 로컬 개발 지원
- AI Search의 Terraform Namespace 관리
- RealtimeKit 관련 업데이트
Vercel의 공식 제품 Changelog에서도 11월 13일 이후 이번 조사 기간에 해당하는 중요한 신규 발표를 확인하지 못했다.
Node.js의 최신 공식 블로그 역시 이번 기간에 해당하는 중요한 신규 안정 릴리스를 제공하지 않았다.
최근 공개된 다음 항목은 이미 이전 브리핑에서 다뤘으므로 반복하지 않았다.
- Cloudflare Durable Objects의 자동 재시도와 내부 Routing 최적화
- Vercel Schedules 및 Sandbox 시작 속도 개선
- Google App Engine Direct VPC Egress
- Amazon EKS Dynamic Resource Allocation
- Amazon OpenSearch의 Clone 기반 업그레이드
- Cloudflare Hyperdrive 연결 한도 확대
이번 기간에는 새로운 주요 서버리스 기능이나 데이터베이스 API의 정식 출시를 1차 원문으로 검증할 수 없었다.
- Cloudflare 공식 Changelog: https://developers.cloudflare.com/changelog/
- Vercel 공식 Changelog: https://vercel.com/changelog
- AWS 공식 발표: https://aws.amazon.com/about-aws/whats-new/
- Google Cloud 공식 Release Notes: https://docs.cloud.google.com/release-notes/
단순한 제품 문서 수정이나 기존 기능의 재소개를 새로운 발표로 포함하지 않았다.
4️⃣ 개발 도구 및 보안
Biome CLI 2.6.8 정식 출시 — Vue·TypeScript·테스트 코드의 신규 Lint 규칙과 기존 분석 성능 개선
- 발표일: 2026-11-15
- GitHub 릴리스 표시 시각: 14:35 — 정확한 시간대 미확인
- 버전:
@biomejs/biome@2.6.8 - 안정화 단계: 정식 패치 릴리스. 신규 규칙은 대부분 Nursery 단계
- 적용 대상: JavaScript, TypeScript, Vue, YAML, package.json, 테스트 코드
- 발표 성능: 기본 Lint 규칙의 실행 시간 약 3~5% 개선, 일부 TypeScript 프로젝트에서 최대 11% 개선
- 측정 주체: Biome 개발팀의 자체 측정. 독립적인 Benchmark 미확인
- 원문: https://github.com/biomejs/biome/releases/tag/@biomejs%2Fbiome@2.6.8
Biome가 2.6.8을 공개했다.
이번 업데이트는 새로운 메이저 버전이 아니다. 하지만 실제 JavaScript와 TypeScript 프로젝트에서 발견할 수 있는 오류의 범위를 크게 확대했다.
특히 Vue에서 비동기 Computed Property를 사용하거나 defineModel()의 기본값을 잘못 설정하는 문제를 찾는 규칙이 추가됐다.
또한 JavaScript의 이벤트 처리와 Promise, Node.js Module Loading, 테스트 Mock 및 패키지 라이선스 검증에 관한 규칙도 포함됐다.
중요한 점은 새롭게 추가된 규칙들이 대부분 Nursery 단계라는 사실이다.
Nursery는 규칙의 안정화가 완료되지 않았거나 향후 동작과 설정이 변경될 수 있는 영역이다.
따라서 Biome 2.6.8로 업데이트했다는 이유만으로 모든 신규 규칙이 기존 프로젝트에서 자동으로 강제된다고 판단해서는 안 된다.
Vue의 비동기 Computed 검사
새로운 규칙 가운데 하나는 다음과 같다.
noVueAsyncComputed
Vue의 Computed Property는 기존 반응형 상태에서 계산할 수 있는 값을 표현할 때 사용한다.
예를 들어 다음 두 값이 있다고 가정해 보자.
- 상품 가격
- 상품 수량
총금액은 두 값의 곱으로 계산할 수 있다.
이러한 경우 Computed Property를 사용할 수 있다.
하지만 Computed 내부에서 비동기 작업을 수행하면 문제가 발생할 수 있다.
예를 들어 다음 코드다.
computed: {
async user() {
return fetchUser(this.userId);
}
}
이 경우 Computed는 실제 사용자 데이터가 아니라 Promise를 반환할 수 있다.
또한 비동기 처리의 완료 시점과 반응형 의존성의 추적 시점이 서로 달라질 수 있다.
Computed는 동기적으로 값을 계산하는 데 적합한 기능이므로 서버 데이터 조회와 같은 비동기 작업은 별도의 상태 또는 데이터 로딩 계층에서 처리하는 편이 적합할 수 있다.
이번 규칙은 다음과 같은 비동기 동작을 검사한다.
asyncawait- Promise
setTimeout()nextTick()
다만 이 규칙이 비동기 데이터 로딩을 대신 구현하거나 실제 Promise의 상태를 자동으로 관리하는 것은 아니다.
정적 분석 단계에서 문제가 될 수 있는 코드 패턴을 알려주는 것이다.
defineModel()의 기본값 불일치
다음 Vue 규칙도 추가됐다.
noVueDefineModelDefault
Vue에서는 defineModel()을 이용해 부모와 자식 컴포넌트 사이의 v-model 연결을 정의할 수 있다.
예를 들어 부모 컴포넌트가 자식 Input에 값을 전달한다고 가정해 보자.
하지만 부모의 값은 아직 undefined다.
반면 자식 컴포넌트에서는 다음 기본값을 사용한다.
const model = defineModel({
type: String,
default: ""
});
이 경우 자식 컴포넌트는 빈 문자열을 가진다.
하지만 부모는 여전히 undefined를 유지할 수 있다.
따라서 두 컴포넌트가 같은 Model을 공유한다고 생각했지만 실제 값이 서로 다르게 나타날 수 있다.
이러한 문제는 Form과 입력 컴포넌트에서 발견하기 어려울 수 있다.
예를 들어 화면에는 빈 문자열이 표시된다.
하지만 실제 제출 데이터에는 undefined가 존재할 수 있다.
이번 규칙은 defineModel()에 기본값을 지정하는 패턴을 검사한다.
다만 모든 애플리케이션이 같은 초기값 정책을 가져야 한다는 의미는 아니다.
실제로 초기값을 어느 컴포넌트에서 소유할지 명확하게 결정해야 한다.
Vue 3에서 제거된 문법 검사
기존 Vue 문법에 관한 규칙도 추가됐다.
대표적인 규칙은 다음과 같다.
noVueDeprecatedFilternoVueDeprecatedVIsnoVueExportInScriptSetup
예를 들어 Vue 2에서는 다음과 같은 Filter 문법을 사용할 수 있었다.
<p>{{ price | currency }}</p>
하지만 Vue 3에서는 해당 Filter 문법이 제거됐다.
따라서 기존 Vue 2 프로젝트를 이전하는 과정에서 이러한 코드가 남아 있으면 문제가 발생할 수 있다.
noVueDeprecatedFilter는 해당 패턴을 탐지한다.
noVueDeprecatedVIs는 이전의 v-is Directive 사용을 검사한다.
noVueExportInScriptSetup은 <script setup> 안에서 허용되지 않는 일반적인 export를 탐지한다.
예를 들어 다음 코드는 문제가 될 수 있다.
<script setup>
export const message = "Hello";
</script>
다만 TypeScript의 타입 Export는 허용된다.
이번 규칙들은 Vue의 새로운 Runtime 기능을 제공하는 것이 아니라 기존 문법과 컴파일 제약을 정적 분석 단계에서 확인하는 기능이다.
비동기 이벤트의 currentTarget 접근
브라우저 이벤트와 관련된 신규 규칙도 포함됐다.
noLateCurrentTargetAccess
예를 들어 사용자가 저장 버튼을 클릭했다고 가정해 보자.
애플리케이션은 클릭한 버튼을 비활성화한다.
이후 서버에 데이터를 저장한다.
저장이 완료되면 버튼을 다시 활성화한다.
다음과 같은 코드를 작성할 수 있다.
element.addEventListener("click", async (event) => {
await save();
event.currentTarget.disabled = false;
});
문제는 event.currentTarget의 수명이다.
이 값은 현재 이벤트가 전달되는 대상과 연결된다.
하지만 이벤트의 Dispatch가 완료된 이후에는 null이 될 수 있다.
따라서 await 이후 해당 값에 접근하면 예상하지 못한 오류가 발생할 수 있다.
이번 규칙은 이러한 코드를 검사한다.
실제로는 비동기 작업을 시작하기 전에 필요한 요소의 참조를 저장하는 방법을 사용할 수 있다.
다만 정적 분석 도구가 모든 비동기 실행 경로를 완벽하게 이해한다고 보장할 수는 없다.
이번 규칙은 알려진 위험 패턴을 찾는 기능이다.
Promise를 객체에 Spread하는 문제
다음 규칙도 추가됐다.
noMisusedSpread
이 규칙은 TypeScript의 타입 정보를 이용해 예상하지 못한 Spread 사용을 탐지한다.
예를 들어 다음 코드를 생각해 보자.
async function getUser() {
return { name: "Kim" };
}
const user = { ...getUser() };
개발자는 user에 이름이 포함될 것으로 기대할 수 있다.
하지만 getUser()는 Promise를 반환한다.
따라서 실제 데이터를 얻으려면 비동기 작업의 결과를 기다려야 한다.
{ ...getUser() }는 Promise의 내부 데이터 객체를 펼치는 작업이 아니다.
이번 규칙은 이러한 패턴을 검사한다.
또한 다음 객체의 Spread 사용도 분석할 수 있다.
- 함수
- Map
- Promise
- Array
- Iterable
- Class Instance
다만 실제로 허용되는 Spread 방식은 대상이 배열인지 객체인지에 따라 달라진다.
예를 들어 배열을 새로운 배열에 펼치는 작업과 배열을 객체에 펼치는 작업은 의미가 다르다.
이번 규칙은 이러한 차이를 타입 정보와 함께 분석한다.
Node.js Module Loading 규칙
다음 규칙도 새롭게 추가됐다.
noBufferConstructornoDynamicRequireuseTopLevelRequireuseValidNamespaceImports
noBufferConstructor는 기존 Node.js의 Buffer() 및 new Buffer() 사용을 검사한다.
기존 생성자는 전달한 값의 타입에 따라 동작이 달라질 수 있어 혼동을 만들 수 있다.
대신 목적에 따라 다음 메서드를 선택할 수 있다.
Buffer.from()Buffer.alloc()Buffer.allocUnsafe()
하지만 Buffer.allocUnsafe()는 초기화되지 않은 메모리를 반환할 수 있다.
따라서 단순히 성능을 높이기 위해 무조건 사용해서는 안 된다.
noDynamicRequire는 다음처럼 런타임에서 Module 이름을 조합하는 패턴을 검사한다.
require("./locales/" + language);
이러한 코드는 Bundler가 실제 의존성을 미리 분석하기 어렵게 만들 수 있다.
옵션을 활성화하면 동적인 import()도 검사할 수 있다.
useValidNamespaceImports는 다음과 같은 상황을 탐지한다.
import * as utils from "./utils.js";
utils.subtract(2, 1);
하지만 utils.js에서 subtract를 Export하지 않았다면 실제 실행에서 오류가 발생할 수 있다.
이번 규칙은 이러한 Module의 Export 관계를 검사한다.
테스트 코드의 Assertion과 Mock 처리
테스트 코드에 관한 규칙도 추가됐다.
대표적으로 다음과 같다.
useCalledWithuseExpectToHaveBeenCalleduseExpectToHaveBeenCalledTimesuseSpyOn
예를 들어 다음 Assertion을 생각할 수 있다.
expect(sendEmail).toHaveBeenCalled();
이 코드는 함수가 호출됐는지 확인한다.
하지만 실제 어떤 인자로 호출됐는지는 검사하지 않는다.
따라서 이메일 주소가 잘못 전달되더라도 테스트를 통과할 수 있다.
useCalledWith는 이러한 패턴을 검사한다.
다만 실제 인자가 중요하지 않은 테스트도 존재할 수 있다.
따라서 모든 테스트에서 무조건 toHaveBeenCalledWith()를 사용해야 하는 것은 아니다.
useSpyOn은 기존 객체의 메서드를 직접 Mock 함수로 덮어쓰는 패턴을 검사한다.
예를 들어 다음 코드다.
Date.now = jest.fn(() => 10);
이 방식에서는 원래 Date.now 구현을 잃을 수 있다.
반면 jest.spyOn()이나 vi.spyOn()을 사용하면 실제 원본 메서드를 복원하는 작업을 더 명확하게 처리할 수 있다.
이러한 문제는 여러 테스트가 같은 프로세스에서 실행되는 환경에서 중요하다.
하나의 테스트가 전역 객체를 변경한 상태를 남겨두면 다른 테스트에 영향을 줄 수 있기 때문이다.
패키지 라이선스 검증
이번 업데이트에는 package.json의 License Field를 검사하는 규칙도 포함됐다.
규칙 이름은 다음과 같다.
usePackageJsonValidLicense
예를 들어 다음 값을 사용했다고 가정해 보자.
{
"name": "my-package",
"license": "GPL3"
}
하지만 GPL3는 올바른 SPDX License Identifier가 아니다.
이번 규칙은 이러한 값을 탐지한다.
지원 대상에는 다음 표현이 포함된다.
- SPDX License Identifier
- SPDX License Expression
UNLICENSED- 실제 License 파일의 참조
예를 들어 다음 표현을 사용할 수 있다.
SEE LICENSE IN LICENSE.md
이번 규칙은 실제 패키지의 Metadata가 올바르게 작성됐는지 검사하는 기능이다.
하지만 License Field가 문법적으로 유효하다고 해서 프로젝트의 모든 의존성이 라이선스 정책을 준수한다는 의미는 아니다.
실제 의존성의 라이선스 및 사용 조건은 별도로 검토해야 한다.
YAML 구조 검사
YAML 파일에 관한 규칙도 추가됐다.
대표적으로 다음과 같다.
noYamlEmptyMapKeysnoYamlEmptyMapValuesnoYamlEmptySequenceEntries
예를 들어 다음 YAML을 생각할 수 있다.
fruits:
- apple
-
- banana
두 번째 목록 항목은 비어 있다.
실제로 의도한 빈 항목일 수도 있지만, 설정을 작성하는 과정에서 값을 누락했을 가능성도 있다.
새로운 규칙은 이러한 패턴을 검사한다.
YAML은 GitHub Actions나 여러 배포 설정에서 널리 사용된다.
따라서 실제 설정 파일의 구조 오류를 더 일찍 발견하는 데 활용할 수 있다.
다만 빈 값이 실제로 허용되는 Schema도 존재할 수 있다.
따라서 Lint 규칙의 결과와 해당 서비스의 실제 설정 Schema를 구분해야 한다.
타입 분석의 정확성 개선
Biome는 신규 규칙 외에도 기존 Type-aware Analysis를 개선했다.
예를 들어 다음 조건을 생각할 수 있다.
if (typeof value === "string") {
// ...
}
TypeScript는 조건문 안에서 value를 String으로 좁혀 해석할 수 있다.
Biome도 이러한 타입 정보를 사용해 불필요한 조건이나 잘못된 Promise 처리를 검사한다.
이번 버전에서는 실제 명시적인 타입 선언이 없는 로컬 변수와 함수 인자에 대해서도 타입 범위를 더 정확하게 좁히도록 변경했다.
관련 대상에는 다음 조건이 포함된다.
typeof- Equality Check
- Nullish Check
- Truthiness Check
- Early Return
- Short-circuit Expression
이번 변경은 다음 규칙의 정확성에도 영향을 줄 수 있다.
noUnnecessaryConditionsnoFloatingPromises
또한 {} 타입의 값이 항상 Truthy라고 잘못 판단하던 일부 상황을 수정했다.
따라서 실제 조건문 분석에서 불필요한 경고가 감소할 가능성이 있다.
Lint 성능 개선
이번 릴리스에는 실제 성능 최적화도 포함됐다.
대상 규칙은 다음과 같다.
noRedeclarenoUnsafeDeclarationMerging
개발팀은 큰 프로젝트에서 기본 Lint 규칙을 실행할 때 다음 개선이 있었다고 발표했다.
| 측정 대상 | 발표된 개선 |
|---|---|
| 대규모 프로젝트의 기본 Lint | 약 3~5% 빠름 |
| 일부 TypeScript 프로젝트 | 최대 11% 빠름 |
하지만 이 수치는 Biome 개발팀의 자체 Benchmark다.
실제 프로젝트에서 같은 결과가 발생한다고 보장할 수 없다.
또한 이번 개선은 특정 Lint 규칙의 분석 비용과 관련된다.
전체 Formatter와 Linter의 모든 작업이 같은 비율로 빨라지는 것은 아니다.
기타 수정
이번 업데이트에는 다음 수정도 포함됐다.
- HTML Formatter에서 일부 주석이 중복 출력되던 문제 수정
noDistractingElements의 잘못된 자동 수정 범위 조정- TypeScript 타입 추론 정확성 개선
- Vue 이벤트 Handler의 표현 방식 일관성 검사
- Vue에 등록한 컴포넌트 이름의 대소문자 규칙 검사
특히 HTML Formatter에서는 요소의 시작 태그와 같은 줄에 주석이 존재할 때 중복 출력될 수 있던 문제가 수정됐다.
이러한 문제는 실제 Formatter 실행 이후 HTML 구조가 의도와 다르게 변경되는 것을 방지하기 위한 것이다.
Nursery 규칙과 운영 환경
이번 릴리스의 새로운 규칙을 적용할 때 가장 중요한 부분은 안정화 단계다.
다수의 규칙은 Nursery에 포함돼 있다.
따라서 새로운 규칙을 활성화하면 기존 프로젝트에서 예상보다 많은 진단이 나타날 수 있다.
또한 해당 규칙의 동작과 옵션이 이후 변경될 수 있다.
따라서 정식 릴리스에 포함됐다는 사실과 규칙 자체가 완전히 안정화됐다는 사실을 구분해야 한다.
이번 업데이트는 Vue의 반응형 상태 오류와 JavaScript·TypeScript의 잘못된 코드 패턴, 테스트 코드 및 패키지 Metadata를 더 넓게 분석할 수 있도록 Biome의 정적 분석 범위를 확장한 정식 패치다.
이번 조사 범위에서 이외에 포함할 만한 주요 신규 개발 도구 및 보안 발표는 확인하지 못했습니다.
Node.js, Deno, Bun, Vite, webpack, Rollup, esbuild, Babel, ESLint, Prettier, npm, pnpm, Yarn, GitHub, GitLab과 주요 테스트·배포 도구의 공식 릴리스를 검토했다.
확인한 주요 기존 릴리스는 다음과 같다.
- Node.js의 11월 11일 보안 릴리스
- Vite 8.3.8: 11월 11일 공개
- Prettier 3.10.1: 11월 12일 공개
- Rollup 4.68.3: 11월 13일 공개
- pnpm 12.21: 11월 13일 공개
- ESLint 10.15: 11월 13일 공개
이러한 항목은 이번 24시간 안에 새롭게 발표된 주요 기능으로 확인되지 않아 반복하지 않았다.
GitHub의 공식 Changelog에서도 조사 기간에 해당하는 중요한 신규 발표를 확인하지 못했다.
OWASP와 주요 공급망 보안 권고 역시 조사했으며, 새롭게 공개된 취약점과 영향 버전, 실제 수정 버전을 1차 원문으로 함께 검증할 수 없는 항목은 포함하지 않았다.
📚 추천 글
脱WordPress:10年超の個人ブログをAstro + Cloudflare Workersへ移行しPageSpeed 100点を実現
- 원제: 脱WordPress:10年超の個人ブログをAstro + Cloudflare Workersへ移行しPageSpeed 100点を実現
- 저자: 星影
- 매체: Zenn
- 게시일: 2026-11-13, 11월 15일 내용 보완
- 기술: Astro, Cloudflare Workers, Static Assets, R2, Pagefind, Sveltia CMS, DNS, 웹 성능
- 원문: https://zenn.dev/unsoluble_sugar/articles/8cdf1efc01e6cb
10년 이상 운영한 WordPress 블로그를 Astro와 Cloudflare Workers 기반의 정적 사이트로 이전하면서 기존 URL과 콘텐츠를 유지한 실제 마이그레이션 기록이다.
이번 글은 단순히 WordPress 데이터를 Markdown으로 변환하는 방법을 소개하지 않는다.
실제로 2,000개 이상의 게시글과 수만 장의 이미지를 이전하면서 발생한 데이터 변환, 검색 엔진 호환성, DNS 전환, 이미지 저장소, 성능 및 비용 문제를 설명한다.
특히 정적 사이트로 변경한다고 해서 모든 성능과 운영 비용 문제가 자동으로 해결되는 것은 아니라는 점이 실제 측정 결과에서 나타난다.
기존 블로그의 규모
저자가 이전한 블로그의 규모는 다음과 같다.
| 항목 | 규모 |
|---|---|
| 기존 WordPress 게시글 | 약 2,000개 |
| 고정 페이지 | 5개 |
| 카테고리 | 165개 |
| 태그 | 3,224개 |
| 상품 링크 데이터 | 1,273개 |
| 생성한 HTML | 6,755페이지 |
| Astro 빌드 시간 | 약 15초 + Pagefind |
| Pagefind 검색 인덱스 | 약 17MB |
이러한 규모에서는 게시글의 실제 HTML을 수작업으로 이전하기 어렵다.
또한 기존 URL을 변경하면 외부 링크와 검색 엔진의 기존 색인에 영향을 줄 수 있다.
따라서 저자는 기존의 경로를 유지하는 것을 중요한 조건으로 설정했다.
WordPress Export 데이터의 문제
WordPress에서는 WXR 형식으로 콘텐츠를 Export할 수 있다.
WXR은 XML 기반의 데이터 형식이다.
저자가 내보낸 파일의 크기는 약 270MB였다.
하지만 해당 파일에는 XML 규격에서 허용하지 않는 제어 문자가 포함돼 있었다.
따라서 일반적인 XML Parser로 파일 전체를 읽으려고 하면 오류가 발생했다.
저자는 이를 해결하기 위해 Python Script를 사용했다.
그리고 <item>...</item> 단위로 게시글 데이터를 분리했다.
이후 필요한 필드를 추출하고 게시글별 HTML 파일을 생성했다.
하지만 정규식으로 XML을 처리하는 방식은 일반적인 XML 파싱의 완전한 대체 수단이 아니다.
실제 데이터 구조가 달라지면 파싱 결과가 잘못될 수 있다.
따라서 이번 방법은 저자가 가진 WXR 파일의 실제 문제를 해결하기 위한 선택이었다.
오래된 글을 Markdown으로 변환하지 않은 이유
저자는 기존 WordPress 글을 전부 Markdown으로 변환하지 않았다.
대신 실제 HTML을 유지했다.
이유는 기존 글에 다음 요소가 포함돼 있었기 때문이다.
- WordPress Block Editor의 Class
- Shortcode
- Gallery
- 이미지 Caption
- 외부 콘텐츠 Embed
- 상품 링크 관련 플러그인 표현
이러한 콘텐츠를 무조건 Markdown으로 변환하면 기존 디자인과 구조가 손상될 수 있다.
따라서 원본 HTML을 유지한다.
이후 Astro의 renderBody()에서 필요한 변환을 처리한다.
반면 새롭게 작성하는 게시글은 Markdown을 사용한다.
저자는 두 종류의 콘텐츠를 동일한 데이터 구조로 표현하도록 했다.
이렇게 하면 기존 글과 새로운 글이 같은 Layout을 사용할 수 있다.
기존 URL 유지
기존 WordPress의 게시글 경로는 다음과 같았다.
/YYYYMMDD/HHMMSS/
저자는 해당 경로를 그대로 유지했다.
또한 WordPress의 이전 Query Parameter도 처리했다.
예를 들어 다음 URL이다.
/?p=123
이러한 요청은 실제 게시글의 새 URL로 Redirect한다.
검색 URL도 별도로 변환한다.
예를 들어 다음 요청이다.
/?s=iPhone
이 요청은 다음 형태의 검색 화면으로 이동하도록 처리한다.
/search/?q=iPhone
이러한 방식은 기존 외부 링크의 동작을 유지하는 데 도움이 된다.
하지만 URL을 유지한다는 사실만으로 검색 엔진의 모든 평가가 자동으로 이전된다고 보장할 수는 없다.
실제 Redirect와 Canonical URL, Sitemap 등을 검증해야 한다.
Workers Static Assets의 분리
이번 마이그레이션의 중요한 설계는 Worker가 모든 요청을 처리하지 않는다는 점이다.
저자는 실제 Worker가 실행해야 하는 경로만 지정했다.
대표적으로 다음과 같다.
{
"assets": {
"run_worker_first": [
"/",
"/wp/*",
"/api/*"
]
}
}
각 경로의 역할은 다음과 같다.
| 경로 | 처리 |
|---|---|
/ | 이전 WordPress URL의 Redirect |
/wp/* | 기존 이미지 제공 |
/api/* | 관리 API 및 외부 API Proxy |
| 그 밖의 경로 | 정적 파일 직접 제공 |
이렇게 하면 일반적인 게시글 HTML과 CSS, JavaScript 요청은 Worker의 코드 실행 없이 제공할 수 있다.
반면 실제 로직이 필요한 요청만 Worker를 거치게 된다.
따라서 모든 페이지 요청마다 별도의 서버 코드를 실행할 필요가 줄어든다.
이미지 3만 장의 단계적 이전
저자의 블로그에는 약 3만 장의 이미지가 존재했다.
Thumbnail 등을 모두 포함하면 약 24만 5,000개 파일이 있었다.
이러한 파일을 한 번에 모두 이전하려면 시간이 필요하다.
저자는 실제 사이트를 공개하기 전에 모든 이미지 이전을 완료하지 않았다.
대신 다음 순서로 이미지를 찾도록 했다.
- Cloudflare R2
- 기존 이미지 저장소
- 실패 시 오류 처리
이렇게 하면 실제 이미지가 아직 R2로 이전되지 않았더라도 기존 저장소의 이미지를 제공할 수 있다.
이후 점진적으로 이미지를 복사했다.
11월 15일 추가 기록에서는 R2 이전을 완료하고 기존 저장소 Fallback을 제거했다고 설명했다.
이러한 구조는 콘텐츠 이전과 실제 서비스 공개 시점을 분리하는 방법이다.
DNS 전환의 40초 공백
이번 글에서 흥미로운 운영상의 문제는 실제 도메인을 변경하는 과정이다.
Cloudflare Workers의 Custom Domain을 사용하려면 기존 도메인의 A Record와 충돌할 수 있었다.
따라서 기존 A Record를 제거해야 했다.
하지만 새로운 Worker에 Custom Domain을 연결하기 전까지는 실제 도메인의 응답이 정상적으로 제공되지 않을 수 있다.
저자는 다음 순서로 작업했다.
- 기존 A Record 제거
- Worker에 Custom Domain 연결
- 새로운 버전 배포
- 실제 URL과 Redirect 검증
실제로 사이트가 표시되지 않은 시간은 약 40초였다.
이러한 결과는 저자 자신의 마이그레이션에서 관찰한 수치다.
모든 Cloudflare 도메인 전환이 같은 시간 안에 완료된다는 의미는 아니다.
정적 사이트인데 모바일 성능이 66점
마이그레이션 이후 저자는 PageSpeed Insights를 실행했다.
정적 사이트라면 처음부터 매우 빠를 것으로 예상했다.
하지만 모바일 Performance Score는 66점이었다.
초기 측정 결과는 다음과 같았다.
- FCP: 4.6초
- LCP: 4.6초
- TBT: 220ms
- Speed Index: 5.8초
- CLS: 0
즉 정적 HTML을 제공하고 있었지만 실제 사용자에게 표시되는 주요 콘텐츠는 빠르지 않았다.
원인은 주로 다음 두 영역이었다.
- 외부 광고 및 분석 Script
- 지나치게 큰 이미지
외부 Script의 지연 로딩
저자는 광고와 분석 관련 Script의 로딩 시점을 변경했다.
대표적으로 다음 조건을 이용했다.
- 페이지 Load 완료
requestIdleCallback()- 실제 사용자 상호작용
- 일정 시간 경과
이렇게 하면 초기 화면을 표시하는 동안 불필요하게 외부 Script가 실행되는 상황을 줄일 수 있다.
하지만 중요한 트레이드오프가 존재했다.
광고 Script를 늦게 로딩하면 사용자가 페이지를 빠르게 닫는 경우 광고가 표시되지 않을 수 있다.
또한 분석 Script가 늦게 로딩되면 일부 방문 기록이 수집되지 않을 수 있다.
저자는 이러한 비용을 고려해 로딩 시점을 선택했다.
즉 단순히 Lighthouse 점수를 높이기 위한 변경만은 아니었다.
실제 광고와 분석 데이터의 손실 가능성도 함께 고려해야 했다.
이미지 최적화 비용의 문제
저자는 처음에 Cloudflare Image Transformations를 사용했다.
실제로 다음 결과를 확인했다.
- 일부 아이캐치 이미지: 277KB → 13KB
- 홈페이지 전송량: 3.3MB → 324KB
하지만 이미지 변환 기능에는 사용량과 요금 제한이 존재한다.
특히 저자의 사이트에는 이미지가 매우 많았다.
여러 크기의 이미지를 srcset으로 제공하면 실제 변환 조합도 증가한다.
따라서 저자는 이후 이미지 변환에 관한 종량제 비용 문제가 발생하자 구현 방식을 변경했다.
11월 15일 추가 기록에 따르면 현재는 이미지를 미리 축소하고 WebP로 변환해 R2에서 제공한다.
이러한 변경은 실제 이미지 전송 비용과 변환 비용 사이의 트레이드오프를 보여준다.
최종 성능 결과
저자가 공개한 PageSpeed Insights 측정 결과는 다음과 같았다.
| 지표 | 변경 전 | 변경 후 |
|---|---|---|
| 모바일 Performance | 66 | 100 |
| FCP | 4.6초 | 0.9초 |
| LCP | 4.6초 | 0.9초 |
| TBT | 220ms | 60ms |
| Speed Index | 5.8초 | 1.0초 |
| CLS | 0 | 0 |
하지만 중요한 제한사항이 있다.
이 표는 Cloudflare의 동적 이미지 변환을 사용하던 시점의 결과다.
11월 15일에는 이미지 제공 방식을 다시 변경했다.
따라서 현재의 최종 구성에서 동일한 PageSpeed 점수가 유지된다고 해당 표만으로 확정할 수 없다.
또한 측정은 저자가 직접 수행한 PageSpeed Insights 결과다.
실제 사용자 28일 데이터를 기반으로 한 장기적인 비교 결과는 별도로 필요하다.
AI 에이전트의 작업 범위
저자는 이번 마이그레이션의 많은 작업을 Claude에 맡겼다.
대표적으로 다음과 같다.
- 변환 Script 구현
- Astro Template 작성
- CSS 수정
- 테스트
- DNS 설정 변경
- Git Commit과 Push
- 배포 실행
- 성능 측정
하지만 실제 운영 환경에 영향을 주는 변경에는 사람의 승인을 요구했다.
예를 들어 다음 작업이다.
- 실제 DNS 변경
- 운영 환경 배포
저자는 명시적인 승인을 받은 뒤 작업을 실행하도록 했다.
따라서 AI가 작업을 자동화하더라도 실제 운영 환경의 최종 변경 권한은 사람이 관리하는 구조였다.
실제 마이그레이션의 한계
이번 사례는 한 개인 블로그의 이전 기록이다.
따라서 다음 환경까지 동일한 방식으로 이전할 수 있다고 보장하지 않는다.
- 복잡한 회원 인증
- 실시간 댓글 기능
- WordPress 기반 전자상거래
- 동적인 개인화 페이지
- 서버에서 실행하는 복잡한 플러그인
또한 정적 사이트로 이전하면 기존 WordPress의 서버 측 기능을 모두 그대로 사용할 수 있는 것은 아니다.
저자는 실제로 일부 상품 검색 API를 다른 서비스로 교체해야 했다.
이번 글은 장기간 운영한 대규모 콘텐츠 사이트를 정적 프레임워크로 이전할 때 데이터 변환, 기존 URL, 이미지 저장소, DNS, 실제 페이지 성능 및 운영 비용을 함께 설계해야 한다는 점을 구체적인 코드와 측정 결과로 보여준다.
Two of our 1,029 page files are client components, and two pages 23 KB apart in HTML ship byte-identical JavaScript
- 원제: Two of our 1,029 page files are client components, and two pages 23 KB apart in HTML ship byte-identical JavaScript
- 저자: Daniel Pertu
- 매체: DEV Community
- 게시일: 2026-11-15 — 정확한 게시 시각 미확인
- 기술: Next.js, React Server Components, TypeScript, JavaScript Bundle,
server-only - 원문: https://dev.to/daniel_pertu/two-of-our-1029-page-files-are-client-components-and-two-pages-23-kb-apart-in-html-ship-2me
실제 운영 중인 Next.js 애플리케이션에서 Server Components와 Client Components의 사용 범위를 전체 코드베이스 기준으로 조사하고, 실제 페이지가 다운로드하는 JavaScript 파일을 비교한 기술 글이다.
저자는 처음에 자신의 프로젝트에 Client Component가 매우 많을 것으로 예상했다.
하지만 실제 코드에서 'use client'를 검색한 결과는 달랐다.
전체 파일 가운데 Client Component를 포함한 파일은 일부였다.
특히 실제 페이지 파일 대부분은 Server Component였다.
그런데도 일반적인 콘텐츠 페이지에서 약 1.33MB의 JavaScript가 필요했다.
이러한 결과는 Server Components의 역할과 전체 JavaScript Bundle의 크기를 줄이는 일이 서로 다른 문제라는 점을 보여준다.
실제 코드베이스 규모
저자가 조사한 프로젝트는 CogniPrep다.
주요 파일 규모는 다음과 같았다.
| 디렉터리 | 파일 수 | 'use client' 사용 파일 |
|---|---|---|
| components | 1,062 | 586 |
| lib | 1,407 | 75 |
| app | 1,148 | 11 |
| tests | 507 | 0 |
| scripts | 18 | 0 |
| 전체 | 4,142 | 672 |
전체 파일의 약 16%에 'use client'가 존재했다.
하지만 중요한 수치는 app 디렉터리에 있었다.
해당 프로젝트에는 1,029개의 page.tsx 파일이 존재했다.
그 가운데 Client Component는 단 두 개였다.
나머지 페이지는 Server Component로 작성됐다.
특히 공개 페이지 991개는 모두 Server Component였다.
콘텐츠와 JavaScript의 분리
저자는 두 개의 기업 정보 페이지를 비교했다.
첫 번째 페이지의 Source는 약 130줄이다.
두 번째 페이지는 약 410줄이다.
실제 HTML의 크기도 달랐다.
하지만 두 페이지가 다운로드하는 JavaScript는 같았다.
측정 결과는 다음과 같았다.
| 페이지 | HTML 크기 | Script Chunk 수 | JavaScript 크기 |
|---|---|---|---|
| Eversource 기업 정보 | 138,471B | 19개 | 1,332,041B |
| Australian Defence Force 기업 정보 | 161,150B | 19개 | 1,332,041B |
| Pricing | 146,033B | 19개 | 1,332,549B |
첫 번째와 두 번째 페이지의 HTML 크기는 약 23KB 차이가 났다.
하지만 실제 JavaScript 파일의 URL과 크기는 완전히 같았다.
즉 콘텐츠가 추가됐지만 클라이언트 JavaScript의 크기는 증가하지 않았다.
이러한 구조에서는 서버에서 렌더링하는 콘텐츠를 계속 추가하더라도 해당 콘텐츠를 표현하기 위한 JavaScript를 함께 추가할 필요가 없다.
인터랙티브 페이지의 차이
저자는 실제 클라이언트 상호작용이 필요한 페이지도 비교했다.
대상은 다음 페이지다.
/games/hirevue
이 페이지에는 별도의 상호작용 컴포넌트가 존재했다.
측정 결과는 다음과 같았다.
- HTML: 362,047B
- Script Chunk: 21개
- JavaScript: 1,407,456B
일반적인 콘텐츠 페이지와 비교하면 JavaScript가 75,415B 증가했다.
이 차이는 추가적인 인터랙티브 기능과 관련된 Chunk에서 발생했다.
따라서 실제 사용자가 어떤 기능을 사용하는지에 따라 클라이언트 JavaScript가 추가되는 것을 확인할 수 있다.
1.33MB의 기본 비용
이번 글에서 가장 중요한 부분은 다음 사실이다.
일반적인 콘텐츠 페이지에서도 약 1.33MB의 JavaScript가 존재했다.
저자는 그 원인으로 공통 App Shell을 설명한다.
대표적으로 다음 기능이다.
- Header
- Dropdown Menu
- Theme 처리
- Analytics
- Icon Runtime
- Error Boundary
이러한 기능은 여러 페이지에서 공통으로 사용된다.
따라서 개별 페이지의 콘텐츠가 모두 Server Component로 작성됐더라도 공통 Layout에 필요한 JavaScript가 남는다.
즉 다음 두 목표는 서로 다르다.
첫 번째는 새로운 콘텐츠 페이지를 추가할 때 JavaScript가 증가하지 않도록 하는 것이다.
두 번째는 모든 페이지에서 사용하는 공통 JavaScript의 크기를 줄이는 것이다.
이번 프로젝트는 첫 번째 목표를 비교적 잘 달성했다.
하지만 두 번째 목표에 대해서는 별도의 최적화가 필요할 수 있었다.
server-only의 역할
저자는 다음 Import도 조사했다.
import "server-only";
이 Marker는 특정 Module이 Server Component 환경에서만 사용돼야 한다는 제약을 명시한다.
실제로 Client Component에서 해당 Module을 Import하면 빌드 과정에서 오류를 발생시킬 수 있다.
저자의 프로젝트에서는 16개 Module에 이 Marker가 존재했다.
대표적인 대상은 다음과 같다.
- 데이터베이스 Client
- Supabase Service Role Client
- 외부 서비스 Refresh Token
- 관리자용 데이터 처리
- 내부 스크린샷 저장소
- 특정 사용자 정보 조회
이러한 Module에는 클라이언트에 노출해서는 안 되는 기능이나 인증 정보가 포함될 수 있다.
따라서 단순히 디렉터리 이름을 server로 지정하는 것보다 실제 Import 제약을 사용하는 편이 명확할 수 있다.
server-only도 완전한 보안 경계는 아님
이번 프로젝트의 lib 디렉터리에는 1,407개 파일이 존재했다.
하지만 실제 server-only Marker가 있는 Module은 16개였다.
따라서 대부분의 Module은 실제 코드의 구성과 개발자의 관례에 따라 서버에서 사용되고 있었다.
이번 글은 이러한 차이를 명확하게 인정한다.
또한 server-only는 잘못된 Client Import를 컴파일 단계에서 발견하는 기능이다.
실제 데이터베이스의 인증과 권한을 대신 처리하는 기능은 아니다.
예를 들어 Server Component에서 데이터베이스를 조회한다고 가정해 보자.
실제로 해당 사용자가 다른 사람의 데이터를 읽을 권한이 있는지는 서버의 비즈니스 로직에서 검증해야 한다.
실제 Script 목록 검사
저자는 실제 페이지가 다운로드하는 JavaScript를 확인하는 방법도 설명한다.
대표적으로 다음과 같은 명령을 사용할 수 있다.
curl -s https://cogniprep.app/employers/eversource \
| grep -o '<script src="[^"]*"'
이렇게 하면 서버가 반환한 HTML에서 Script URL을 추출할 수 있다.
이후 다른 페이지의 Script URL과 비교한다.
두 페이지가 같은 Script 목록을 사용한다면 동일한 클라이언트 의존성을 공유하고 있을 가능성이 있다.
하지만 실제 Script URL이 같다는 사실만으로 브라우저가 해당 JavaScript를 매번 다시 다운로드한다는 의미는 아니다.
브라우저 Cache에 따라 전송 비용은 달라질 수 있다.
또한 이번 글의 JavaScript 크기는 Script 파일의 Byte 수를 합산한 것이다.
실제 네트워크의 압축 전송량과 동일하다고 단정해서는 안 된다.
이번 분석의 한계
이번 글은 실제 Source File과 Script URL을 기준으로 계산한 결과다.
하지만 다음 수치는 제공하지 않았다.
- JavaScript 실행 시간
- 실제 Hydration 시간
- 브라우저의 메모리 사용량
- 페이지별 INP
- JavaScript 압축 전송량
따라서 1.33MB의 JavaScript가 존재한다는 사실만으로 해당 사이트의 실제 사용자 성능이 나쁘다고 단정할 수는 없다.
또한 다른 Next.js 프로젝트도 같은 비율의 Client Component를 사용해야 한다는 의미는 아니다.
실제 상호작용의 양과 애플리케이션의 목적에 따라 적절한 구조는 달라질 수 있다.
이번 글은 Server Components가 콘텐츠 증가에 따른 JavaScript 증가를 억제할 수 있지만, 실제 사용자가 다운로드하는 공통 JavaScript의 기본 비용은 별도로 관리해야 한다는 점을 전체 Repository와 실제 배포 HTML의 비교로 설명한다.
React 19.3 View Transitions: The Suspense Patterns That Keep an App Fast
- 원제: React 19.3 View Transitions: The Suspense Patterns That Keep an App Fast
- 저자: Muhammad Zeeshan Sardar
- 매체: DEV Community
- 게시일: 2026-11-12
- 기술: React 19.3, Next.js 16, Suspense, View Transitions, CSS Animation, 접근성
- 원문: https://dev.to/zeeshansardar08/react-193-view-transitions-the-suspense-patterns-that-keep-an-app-fast-2fa9
React의 View Transitions를 실제 애플리케이션에 적용하면서 애니메이션을 어디에 배치해야 UI가 부드럽고 응답성이 유지되는지 설명한 기술 글이다.
이번 글은 React View Transitions의 최초 출시 발표가 아니다.
이미 사용할 수 있는 기능을 Suspense와 Next.js App Router에 적용할 때 발생하는 문제를 분석한다.
특히 중요한 설계 원칙은 다음과 같다.
사용자의 입력에 대한 피드백은 즉시 표시하고, 실제 데이터가 준비됐을 때 발생하는 화면 전환에만 애니메이션을 적용한다.
View Transition이 실행되는 조건
React의 <ViewTransition>은 모든 State 변경에서 자동으로 애니메이션을 실행하지 않는다.
대표적으로 다음 상황과 연결된다.
startTransition()안의 State 변경- Suspense에서 실제 콘텐츠가 준비되는 경우
useDeferredValue()와 관련된 변경
예를 들어 사용자가 Button을 클릭해 새로운 콘텐츠를 표시한다고 가정해 보자.
일반적인 setState()는 긴급한 UI 업데이트로 처리될 수 있다.
이 경우 <ViewTransition>으로 감싸더라도 기대한 애니메이션이 발생하지 않을 수 있다.
반면 다음처럼 startTransition()을 이용하면 해당 업데이트를 Transition으로 처리할 수 있다.
startTransition(() => {
setOpen(true);
});
하지만 모든 사용자 입력을 Transition으로 처리해야 한다는 의미는 아니다.
예를 들어 텍스트 입력창의 값을 변경하는 작업은 가능한 한 즉시 반영하는 편이 적합하다.
Enter·Exit·Update·Share
React에서는 다음 네 종류의 변경을 구분한다.
| 유형 | 상황 |
|---|---|
| Enter | 새로운 요소가 추가됨 |
| Exit | 기존 요소가 제거됨 |
| Update | 기존 요소의 내용이나 위치가 변경됨 |
| Share | 같은 이름을 가진 요소가 서로 다른 위치 사이를 전환 |
예를 들어 상품 목록에서 상세 페이지로 이동한다고 가정해 보자.
상품 목록에는 작은 Thumbnail이 존재한다.
상세 페이지에는 큰 Hero Image가 존재한다.
두 요소에 같은 View Transition 이름을 지정하면 마치 하나의 이미지가 확대되면서 이동하는 것처럼 표현할 수 있다.
이러한 효과를 Shared Element Transition이라고 한다.
하지만 해당 이름은 실제 동시에 존재하는 요소 사이에서 충돌하지 않아야 한다.
따라서 상품 ID와 같은 안정적인 식별자를 이용해 이름을 생성하는 편이 적합하다.
default="none"을 권장하는 이유
이번 글에서 강조하는 설정은 다음과 같다.
default="none"
기본 설정에서는 여러 종류의 UI 변경에 자동 Cross-fade가 적용될 수 있다.
예를 들어 다음 상황이다.
- 페이지 Navigation
router.refresh()- Suspense 콘텐츠 표시
처음에는 이러한 애니메이션이 자연스럽게 보일 수 있다.
하지만 실제 화면에 View Transition Boundary가 많아지면 문제가 발생할 수 있다.
작은 UI 변경마다 Cross-fade가 실행될 수 있기 때문이다.
저자는 필요한 애니메이션만 명시적으로 활성화하는 방식을 권장한다.
예를 들어 다음과 같다.
<ViewTransition
default="none"
enter="slide-up"
>
<SearchResults query={query} />
</ViewTransition>
이렇게 하면 새로운 콘텐츠가 처음 표시될 때만 Enter Animation을 적용할 수 있다.
반면 다른 업데이트에는 불필요한 애니메이션을 적용하지 않는다.
다만 Shared Element Transition을 사용한다면 share도 명시해야 할 수 있다.
Suspense의 Fallback은 즉시 표시
이번 글에서 가장 중요한 부분은 Suspense다.
예를 들어 검색 결과를 서버에서 가져오는 화면을 생각할 수 있다.
사용자는 새로운 검색 조건을 선택한다.
실제 데이터가 준비되기 전에는 Skeleton을 표시한다.
이후 데이터가 준비되면 실제 검색 결과를 표시한다.
저자는 다음 두 작업을 구분한다.
첫 번째는 Skeleton의 표시다.
이 작업은 즉시 수행하는 편이 적합하다.
두 번째는 Skeleton에서 실제 콘텐츠로 변경되는 과정이다.
이 작업에는 부드러운 애니메이션을 적용할 수 있다.
사용자가 버튼을 클릭했는데 Loading UI가 천천히 Fade-in되면 실제 입력에 대한 반응이 지연되는 것처럼 느껴질 수 있다.
반면 실제 결과가 준비된 순간에는 Skeleton과 콘텐츠의 차이를 부드럽게 연결하는 것이 적합할 수 있다.
하나의 Boundary 또는 별도의 Boundary
저자는 두 가지 Suspense 패턴을 비교한다.
첫 번째는 Skeleton과 실제 콘텐츠를 하나의 View Transition Boundary 안에 두는 방식이다.
이 경우 Skeleton이 실제 콘텐츠로 변경되는 과정을 Update Animation으로 표현할 수 있다.
두 번째는 Skeleton과 콘텐츠에 별도의 Boundary를 사용하는 방식이다.
이 경우 Skeleton의 Exit와 콘텐츠의 Enter를 각각 제어할 수 있다.
실제 선택은 두 UI의 구조에 따라 달라진다.
예를 들어 Skeleton과 실제 콘텐츠의 크기가 비슷하다면 Update Animation이 자연스러울 수 있다.
반면 두 화면의 모양이 매우 다르다면 하나의 이미지를 늘리거나 줄이는 효과가 어색할 수 있다.
이 경우 별도의 Enter와 Exit를 사용하는 편이 적합할 수 있다.
캐시된 콘텐츠에서는 애니메이션 생략
이번 글은 이미 데이터가 Cache에 존재하는 상황도 고려한다.
예를 들어 사용자가 이전에 방문한 탭으로 돌아간다고 가정해 보자.
해당 데이터는 이미 메모리에 존재한다.
따라서 실제 콘텐츠를 즉시 표시할 수 있다.
하지만 모든 콘텐츠 변경에 애니메이션을 적용하면 사용자는 이미 준비된 정보를 보기 위해 불필요하게 기다리게 될 수 있다.
저자는 이를 피하기 위해 default="none"을 기본으로 사용하고 필요한 전환만 활성화하도록 설명한다.
다만 실제 Cache Hit 여부와 Suspense Boundary의 동작은 애플리케이션의 데이터 로딩 구조에 따라 달라질 수 있다.
Boundary의 위치
View Transition은 실제 React Tree의 구조에도 영향을 받는다.
예를 들어 다음 구조를 생각할 수 있다.
<div className="card">
<ViewTransition>
<Card />
</ViewTransition>
</div>
저자는 이러한 구조에서 외부 div가 추가되거나 제거되는 경우 내부 View Transition의 Enter·Exit가 기대한 대로 실행되지 않을 수 있다고 설명한다.
반면 다음처럼 실제 추가·제거되는 DOM을 Boundary 안에 포함하면 동작이 달라질 수 있다.
<ViewTransition>
<div className="card">
<Card />
</div>
</ViewTransition>
따라서 단순히 컴포넌트를 <ViewTransition>으로 감쌌다는 사실만으로 모든 애니메이션이 실행되는 것은 아니다.
실제로 어느 DOM Node가 추가되거나 제거되는지 확인해야 한다.
Next.js에서의 방향별 애니메이션
Next.js에서는 다음 속성을 사용할 수 있다.
transitionTypes
예를 들어 사용자가 다음 페이지로 이동한다고 가정해 보자.
이때는 오른쪽에서 왼쪽으로 이동하는 애니메이션을 적용할 수 있다.
반대로 이전 페이지로 돌아간다면 다른 방향의 애니메이션을 사용할 수 있다.
React에서는 addTransitionType()으로 이러한 정보를 전달할 수 있다.
Next.js에서는 관련 Navigation API에서 Transition Type을 전달할 수 있다.
다만 실제 Router API의 지원 범위는 Next.js 버전에 영향을 받는다.
이번 글의 코드가 모든 이전 버전에서 동일하게 동작한다고 가정해서는 안 된다.
애니메이션이 실행되지 않는 경우
저자는 다음 상황을 주요 원인으로 설명한다.
- 실제 업데이트가 Transition이 아님
- View Transition Boundary의 위치가 잘못됨
- Shared Element의 이름이 충돌
- React Key가 안정적이지 않음
- 실제 콘텐츠가 이미 Cache에 존재
flushSync()가 실행됨- 다른 View Transition이 진행 중
특히 이미 애니메이션이 진행되고 있다면 새로운 전환의 실행 시점이 지연될 수 있다.
따라서 애니메이션의 지속 시간이 지나치게 길면 전체 UI가 느리게 느껴질 수 있다.
저자는 실제 애니메이션 시간을 대체로 150~400ms 범위에서 검토하도록 설명한다.
하지만 이 수치가 모든 UI에 적용되는 공식 성능 기준은 아니다.
Reduced Motion과 접근성
View Transitions는 움직임에 민감한 사용자를 고려해야 한다.
대표적인 CSS Media Query는 다음과 같다.
prefers-reduced-motion
사용자가 운영체제에서 움직임을 줄이도록 설정했다면 과도한 이동과 확대 애니메이션을 생략하거나 줄일 수 있다.
또한 포커스 이동을 애니메이션 완료 시점에만 의존하도록 구현하지 않는 편이 적합하다.
예를 들어 새로운 페이지가 표시된 뒤 키보드 포커스를 변경해야 한다면 실제 Navigation 상태와 연결해 처리해야 한다.
애니메이션이 중단되거나 지원되지 않는 브라우저에서도 포커스가 올바르게 이동해야 하기 때문이다.
적용 범위와 한계
이번 글은 실제 React와 Next.js의 API를 이용한 패턴을 분석한다.
하지만 View Transitions를 사용했을 때 실제 INP나 LCP가 얼마나 개선되는지에 관한 독립적인 Benchmark는 제공하지 않았다.
또한 부드러운 애니메이션이 존재한다는 사실이 실제 데이터 로딩 속도를 높이는 것은 아니다.
오히려 불필요한 애니메이션이 많으면 사용자에게 화면이 더 느리게 느껴질 수 있다.
이번 글은 React의 Transition과 Suspense를 결합할 때 애니메이션의 표현보다 실제 사용자 입력의 즉각적인 반응을 우선하고, 필요한 화면 전환에만 선택적으로 움직임을 적용하는 방법을 설명하는 자료다.
Why a CSS rotate with will-change: transform makes images and text blurry
- 원제: Why a CSS rotate with will-change: transform makes images and text blurry
- 저자: Mohamed Gado
- 매체: DEV Community / 개인 기술 블로그
- 게시일: 2026-11-11
- 기술: CSS Transform, Browser Compositing, Next.js Image, AVIF, Device Pixel Ratio
- 원문: https://dev.to/mohamedgado/why-a-css-rotate-with-will-change-transform-makes-images-and-text-blurry-pb0
실제 포트폴리오 웹사이트에서 이미지 파일은 선명한데 브라우저 화면에서는 글자와 이미지가 흐려지는 문제를 분석한 글이다.
저자는 처음에 이미지의 압축 품질이나 해상도가 문제라고 생각했다.
하지만 실제 원인은 하나가 아니었다.
특히 CSS Transform이 적용된 Layer를 브라우저가 재샘플링하면서 작은 글자와 이미지의 경계가 흐려지는 문제가 존재했다.
또한 일부 이미지는 실제 표시 크기에 비해 원본 해상도가 부족했다.
이번 글은 이 두 문제를 구분해 해결한 과정이다.
실제 CSS 구조
저자의 프로젝트에는 여러 Screenshot을 겹쳐 놓은 Card Gallery가 있었다.
각 Card에는 약 0.9도의 회전이 적용됐다.
또한 다음 속성을 사용했다.
will-change: transform
Hover 시에는 다음 변환도 적용했다.
scale(1.045)
예를 들어 다음과 같은 구조다.
.shot {
transition: transform 0.28s ease;
will-change: transform;
}
.shot:nth-child(odd) {
transform: rotate(-0.9deg);
}
.shot:nth-child(even) {
transform: rotate(0.9deg);
}
.shot:hover {
transform: rotate(0deg) scale(1.045);
}
처음에는 이러한 회전이 매우 작으므로 실제 이미지 품질에 큰 영향을 주지 않을 것으로 예상했다.
하지만 실제 Browser Compositor에서는 다른 문제가 발생할 수 있다.
Rasterization과 재샘플링
브라우저는 HTML과 CSS를 실제 Pixel로 렌더링한다.
특정 요소는 별도의 Compositing Layer로 처리될 수 있다.
브라우저가 Layer를 먼저 Rasterize한 뒤 해당 Layer를 회전하거나 확대하면 이미 생성된 Bitmap을 다시 샘플링해야 할 수 있다.
예를 들어 세로로 정확하게 정렬된 1px의 선이 있다고 가정해 보자.
이 선을 0.9도 회전하면 실제 화면의 Pixel Grid와 정확하게 일치하지 않는다.
브라우저는 주변 Pixel의 값을 계산해 회전된 이미지를 표시한다.
그 결과 매우 얇은 선이나 작은 글자의 경계가 부드럽게 보일 수 있다.
이러한 현상은 실제 이미지 파일의 압축 품질이 좋더라도 발생할 수 있다.
실제 브라우저 확인
저자는 다음 환경에서 Computed Style을 확인했다.
- Viewport 너비: 1512px
- Device Pixel Ratio: 2
- 실제 회전 각도: 약 0.9도
- 요청한 이미지:
w=640&q=75
실제 Transform Matrix에서도 회전이 확인됐다.
대표적으로 다음 값이 포함됐다.
matrix(0.999877, -0.0157, ...)
0.9도는 작은 각도다.
하지만 실제 Pixel 단위에서는 회전된 Bitmap의 경계가 다시 계산될 수 있다.
또한 Hover에서 scale(1.045)를 적용하면 이미 Rasterize된 이미지가 확대될 수 있다.
저자의 사례에서는 사용자가 실제로 마우스를 올린 Card가 오히려 가장 흐리게 보였다.
다만 will-change가 존재한다는 사실만으로 모든 브라우저가 항상 정확히 같은 방식으로 Rasterize한다고 보장할 수는 없다.
실제 GPU와 Browser Compositor의 구현에 따라 달라질 수 있다.
회전과 확대 제거
저자는 Card의 회전과 Hover Scale을 제거했다.
또한 will-change: transform도 제거했다.
대신 Hover 시에는 수직 이동만 사용했다.
대표적인 형태는 다음과 같다.
.shot a.image-zoom:hover {
translate: 0 -0.375rem;
}
이렇게 하면 요소를 확대하거나 회전하지 않고 위치만 변경할 수 있다.
다만 translate 역시 실제 이동 거리가 Device Pixel Grid와 맞지 않는다면 재샘플링이 발생할 수 있다.
따라서 모든 Translation이 항상 선명한 결과를 보장하는 것은 아니다.
실제 렌더링 크기와 Pixel 정렬을 고려해야 한다.
이미지 압축 품질
CSS 문제와 별개로 실제 이미지 압축 품질도 영향을 주고 있었다.
저자의 Screenshot은 AVIF Quality 75로 제공됐다.
하지만 작은 UI 텍스트 주변에 압축으로 인한 Ringing이 나타날 수 있었다.
저자는 Quality를 90으로 높였다.
이미지 크기는 다음처럼 증가했다.
- 변경 전: 약 25KB
- 변경 후: 약 31KB
즉 Card 하나당 약 6KB의 추가 전송량이 발생했다.
이러한 변경은 화면의 선명도를 개선하는 데 도움이 됐다.
하지만 모든 AVIF 이미지에서 Quality 90이 가장 적합하다는 의미는 아니다.
실제 이미지의 내용과 원본 해상도에 따라 적절한 품질이 달라진다.
Next.js Image 설정
저자는 Next.js의 Image Optimizer를 사용했다.
이미지의 Width와 Quality를 URL Parameter로 지정했다.
하지만 실제 설정에는 허용하는 이미지 크기와 품질 목록이 존재했다.
따라서 애플리케이션에서 Quality 90을 요청하더라도 실제 Next.js 설정에서 해당 값을 허용해야 했다.
저자는 다음 설정을 수정했다.
images.qualities
또한 실제 Rendered Image URL에서 사용한 Width와 Quality가 Next.js 설정에 포함돼 있는지 검사하는 테스트를 추가했다.
이러한 방식은 CSS의 시각적인 문제와 이미지 최적화 설정의 문제를 별도로 관리하도록 한다.
원본 해상도의 부족
두 번째 문제는 Banner Image에서 발생했다.
원본 Banner의 크기는 다음과 같았다.
1024 × 500
하지만 실제 화면에서는 가로 1086 CSS Pixel로 표시됐다.
기기의 DPR은 2였다.
따라서 실제로 약 2172개의 Device Pixel에 이미지가 표시돼야 했다.
하지만 원본은 1024px에 불과했다.
즉 실제 표시 영역에서 이미지를 약 2.1배 확대해야 했다.
이 경우 원본 이미지에 없는 세부 정보를 브라우저가 새롭게 만들어낼 수는 없다.
따라서 이미지가 흐려질 수 있다.
단순 Upscaling의 한계
저자는 처음에 이미지 파일의 너비를 2560px로 늘리는 방법을 사용했다.
하지만 결과는 선명하지 않았다.
원래 1024px 이미지의 Pixel을 늘렸기 때문이다.
이미지의 파일 크기와 Pixel 수는 증가했다.
하지만 실제 원본에 존재하지 않던 세부 정보가 새롭게 생성되지는 않았다.
저자는 이를 해결하기 위해 SVG 원본에서 Banner를 다시 생성했다.
새로운 크기는 다음과 같았다.
3072 × 1500
또한 실제 이미지의 sizes 속성을 변경했다.
기존에는 768px 너비의 영역을 가정했지만 실제 화면의 Banner는 1086px이었다.
따라서 브라우저가 적절한 이미지 크기를 선택하도록 실제 Layout에 맞는 정보를 제공했다.
이미지 안의 텍스트 문제
하지만 새로운 3072px 이미지에서도 다른 문제가 나타났다.
실제 텍스트가 이미지 안에 포함돼 있었다.
브라우저가 큰 이미지를 작게 표시하면 이미지 안의 글자 역시 축소된다.
이 과정에서 작은 글자의 경계가 흐려질 수 있다.
따라서 저자는 실제 텍스트를 이미지로 제공해야 하는지 검토했다.
예를 들어 다음 정보를 생각할 수 있다.
- 상품 이름
- 부제목
- 설명 문구
이러한 콘텐츠는 가능한 경우 HTML의 실제 텍스트로 제공하는 편이 적합할 수 있다.
실제 텍스트는 브라우저의 Font Rendering을 이용할 수 있다.
또한 사용자가 선택하고 복사하거나 화면을 확대하는 데 더 적합하다.
이번 분석의 한계
이번 글은 실제 운영 사이트에서 발견한 문제를 설명한다.
하지만 변경 전후의 LCP나 INP, GPU 사용량에 관한 Benchmark는 포함되지 않았다.
또한 모든 CSS Transform이 이미지 품질을 떨어뜨린다는 의미는 아니다.
실제 Rasterization과 재샘플링의 결과는 Browser Engine과 기기, 요소의 크기에 따라 달라질 수 있다.
이번 글은 이미지의 선명도를 분석할 때 파일의 해상도와 압축 품질뿐 아니라 CSS Transform, Compositing Layer, 실제 표시 크기 및 Device Pixel Ratio를 각각 검토해야 한다는 점을 구체적인 운영 사례로 보여준다.
Printable LEGO instructions from a three.js viewer: cqw units, headless Edge and a page count
- 원제: Printable LEGO instructions from a three.js viewer: cqw units, headless Edge and a page count
- 저자: Oleksandr Gamanyuk
- 매체: Mister Blocks / DEV Community
- 게시일: 2026-11-15 — 정확한 게시 시각 미확인
- 기술: JavaScript, Three.js, CSS Container Query, Headless Edge, PDF, Service Worker, PWA
- 원문: https://dev.to/misterblocks/printable-lego-instructions-from-a-threejs-viewer-cqw-units-headless-edge-and-a-page-count-5bbh
브라우저에서 Three.js로 표시하는 LEGO 조립 모델을 별도의 PDF 생성 라이브러리 없이 실제 인쇄 가능한 조립 설명서로 만드는 방법을 설명한 기술 글이다.
저자는 온라인에서 3D 모델을 볼 수 있도록 서비스를 만들었다.
하지만 실제로 LEGO를 조립하는 환경에서는 화면보다 종이 설명서가 편리할 수 있었다.
따라서 다음 세 기능을 함께 제공하도록 만들었다.
- 브라우저의 3D Viewer
- 인쇄 가능한 PDF
- 오프라인에서 사용할 수 있는 조립 가이드
이번 글의 특징은 세 기능에 서로 다른 Renderer를 사용하지 않는다는 점이다.
실제 3D 모델을 렌더링하는 코드를 재사용해 인쇄용 이미지를 생성한다.
또한 CSS Container Query Unit을 이용해 화면 미리보기와 실제 인쇄물의 Layout을 일치시킨다.
HTML 자체가 설명서
저자는 별도의 PDF Layout Engine을 구현하지 않았다.
대신 실제 인쇄할 페이지를 HTML로 작성했다.
대표적인 경로는 다음과 같다.
/builds/<name>-lego-build/print
이 페이지는 다음 구조를 가진다.
- 표지
- 단계별 조립 설명
- 부품 목록
각 단계에는 다음 정보가 포함된다.
- 단계 번호
- 필요한 부품
- 조립 방법
- 해당 단계까지 완성된 3D 모델
따라서 실제 브라우저에서는 일반적인 웹페이지로 표시할 수 있다.
그리고 같은 페이지를 인쇄하거나 PDF로 저장할 수 있다.
cqw를 이용한 크기 계산
저자가 사용한 중요한 CSS 기능은 다음 단위다.
cqw
이는 Container Query Width Unit이다.
1cqw는 실제 Query Container의 너비의 1%를 의미한다.
예를 들어 Container 너비가 1000px이라고 가정해 보자.
이때 1cqw는 10px에 해당한다.
저자는 설명서의 요소 크기를 cqw로 정의했다.
따라서 실제 인쇄 용지의 비율이 유지된다면 화면 미리보기와 PDF에서 같은 비율의 Layout을 사용할 수 있다.
예를 들어 다음 요소에 적용할 수 있다.
- 제목 크기
- 이미지 크기
- 여백
- 부품 목록
- 단계 번호
이러한 방식은 화면과 PDF에 각각 독립적인 Pixel 크기를 정의하는 것보다 Layout의 비율을 일관되게 유지하는 데 도움이 된다.
하지만 실제 출력 용지의 비율이 달라지면 Layout도 변경해야 할 수 있다.
Letter와 A4 지원
저자는 다음 두 용지를 지원했다.
- US Letter
- A4
기본값은 US Letter의 가로 방향이다.
사용자는 버튼을 눌러 A4로 변경할 수 있다.
실제 설정에서는 다음 두 요소를 변경한다.
- CSS의
@page규칙 <html>에 적용하는 Class
또한 사용자가 선택한 용지 크기를 저장해 다음에도 유지할 수 있도록 했다.
따라서 인쇄 화면과 실제 PDF의 용지 크기를 별도의 도구에서 설정해야 하는 부담을 줄였다.
Three.js로 단계별 이미지를 생성
저자는 실제 조립 단계마다 별도의 이미지 파일을 보관하지 않았다.
대신 기존 Three.js Viewer를 재사용했다.
예를 들어 다음 세 이미지가 필요하다고 가정해 보자.
첫 번째는 완성된 전체 모델이다.
두 번째는 세 번째 단계까지 조립한 모델이다.
세 번째는 특정 LEGO 부품 하나다.
이러한 이미지는 모두 Three.js에서 생성할 수 있다.
저자는 Viewer를 화면 밖에서 실행한다.
그리고 필요한 상태로 모델을 구성한 뒤 Screenshot을 생성한다.
각 이미지의 카메라 위치도 조절했다.
특히 초기 단계에서는 부품이 적기 때문에 자동으로 확대하면 작은 부품이 페이지 전체를 차지할 수 있다.
이를 방지하기 위해 카메라의 최대 확대 범위를 제한했다.
저자는 전체 모델이 들어가는 거리의 60%보다 가까이 접근하지 않도록 했다.
또한 부품 종류별 이미지는 같은 카메라 거리에서 렌더링했다.
이렇게 하면 1×1 Plate와 2×4 Brick이 실제 크기의 차이를 유지하도록 표현할 수 있다.
별도의 PDF 라이브러리 없이 출력
PDF는 Headless Edge를 이용해 생성했다.
대표적인 명령은 다음과 같다.
msedge \
--headless=new \
--no-pdf-header-footer \
--virtual-time-budget=<ms> \
--print-to-pdf=out.pdf \
<url>?paper=a4
이 방식에서는 브라우저가 실제 HTML과 CSS를 렌더링한다.
이후 인쇄 결과를 PDF로 저장한다.
따라서 서버에서 별도의 PDF 문서 객체와 Layout을 구성할 필요가 없다.
하지만 실제 3D 이미지를 생성하는 데 시간이 필요하다.
특히 복잡한 모델에서는 여러 단계의 Screenshot을 생성해야 한다.
따라서 저자는 Virtual Time Budget을 모델의 복잡도에 따라 변경했다.
기본적으로 약 40초에 부품과 단계 수에 따른 시간을 추가했다.
이러한 방법은 실제 이미지 생성이 완료되기 전에 PDF를 출력하는 문제를 줄이기 위한 것이다.
다만 고정된 시간 예산만으로 모든 기기에서 완료를 보장할 수는 없다.
실제 실행 환경의 성능에 영향을 받기 때문이다.
PDF의 페이지 수 검증
이번 글에서 중요한 부분은 PDF의 완전성을 검증하는 방법이다.
저자는 PDF를 생성한 이후 실제 페이지 수를 계산했다.
예상 페이지 수는 다음 구성으로 결정된다.
- 표지 1페이지
- 조립 단계마다 1페이지
- 부품 종류 40개마다 1페이지
예를 들어 실제 모델이 15단계라면 다음 페이지가 필요하다.
- 표지 1페이지
- 조립 과정 15페이지
- 부품 목록
실제 사례 가운데 하나는 다음 결과를 가진다.
- LEGO 부품 127개
- 조립 단계 15개
- PDF 18페이지
PDF의 페이지 수가 예상과 다르면 해당 결과물을 업로드하지 않는다.
실제 이미지 생성이 완료되지 않았거나 Layout이 예상과 다르게 분리됐을 가능성이 있기 때문이다.
하지만 페이지 수가 맞다는 사실만으로 모든 이미지가 올바르게 렌더링됐다고 완전히 보장할 수는 없다.
예를 들어 같은 페이지 수를 가진 PDF에서도 일부 이미지가 빈 상태일 수 있다.
따라서 페이지 수 검사는 중요한 기본 검증이지만 전체 시각적 회귀 테스트를 대체하지는 않는다.
Cloudflare R2에 PDF 저장
정상적으로 생성한 PDF는 Cloudflare R2에 저장한다.
지원하는 결과물은 다음과 같다.
- Letter
- A4
- 영어
- 우크라이나어
하지만 모든 배포에서 모든 PDF를 다시 생성하지 않는다.
실제 조립 가이드의 내용이 변경된 경우에만 관련 파일을 갱신한다.
따라서 동일한 모델의 PDF를 불필요하게 반복해서 생성하지 않아도 된다.
이러한 구조는 3D Screenshot 생성의 계산 비용을 줄이는 데 도움이 될 수 있다.
오프라인 PWA
이번 사이트는 PWA로 구현됐다.
저자는 Service Worker에서 요청의 종류에 따라 다른 Cache 정책을 사용했다.
| 요청 종류 | 정책 |
|---|---|
| 일반 페이지 | Network First |
| 조립 가이드 데이터 | Network First, Offline Fallback |
| 버전이 포함된 JavaScript | Cache First |
| Three.js 및 Font | Cache First |
| 새로운 디자인 및 Chat | Network Only |
따라서 사용자가 이미 열어본 조립 가이드는 인터넷 연결이 없는 상황에서도 사용할 수 있다.
예를 들어 사용자가 집에서 조립 설명서를 열었다고 가정해 보자.
이후 인터넷 연결이 끊긴 장소에서 같은 가이드를 다시 열 수 있다.
하지만 아직 한 번도 방문하지 않은 가이드는 Cache에 존재하지 않을 수 있다.
따라서 모든 콘텐츠가 처음부터 오프라인에서 사용 가능하다는 의미는 아니다.
오래된 Script로 인한 오류
저자는 실제로 Service Worker 및 브라우저 Cache와 관련된 문제를 겪었다.
새로운 조립 가이드가 공개됐다.
하지만 휴대전화에는 이전 버전의 build.js가 Cache에 남아 있었다.
기존 Script는 새로운 URL 구조를 이해하지 못했다.
따라서 새롭게 공개한 조립 가이드를 열 수 없었다.
저자는 이를 해결하기 위해 정적 파일의 URL에 배포 ID를 포함했다.
대표적인 형태는 다음과 같다.
/app.js?v=<deploy-id>
이렇게 하면 새로운 배포에서 실제 리소스 URL이 변경된다.
따라서 이전 버전의 Cache와 구분할 수 있다.
또한 Service Worker에도 배포 ID를 포함했다.
새로운 Service Worker가 설치되면 이전 배포의 Cache를 정리하도록 했다.
하지만 이러한 방식에서도 Cache 갱신과 Service Worker의 활성화 시점은 브라우저의 정책에 영향을 받을 수 있다.
따라서 실제 배포 이후 여러 탭이 동시에 열려 있는 상황도 고려해야 한다.
외부 리소스의 Cache 용량
저자는 외부 Script와 Font의 Cache에도 주의했다.
특히 실제 CORS 응답을 Cache하는 것과 Opaque Response를 Cache하는 것은 다를 수 있다.
Opaque Response는 실제 내용을 JavaScript에서 직접 확인할 수 없는 응답이다.
이러한 응답을 Cache할 때는 브라우저의 저장 용량 계산에서 예상보다 큰 비용이 발생할 수 있다.
저자는 일부 Opaque Response가 약 7MB의 Quota를 사용할 수 있다고 설명했다.
따라서 모든 외부 리소스를 무조건 Cache하는 방식은 실제 Storage Quota 문제를 만들 수 있다.
이번 프로젝트에서는 Cache할 수 있는 응답의 종류를 제한했다.
구현의 한계
이번 글은 실제 운영 중인 서비스를 기반으로 작성됐다.
하지만 다음 성능 수치는 제공하지 않았다.
- Three.js Screenshot 생성의 평균 시간
- PDF 생성 시간의 P95
- 실제 모바일 기기의 메모리 사용량
- Service Worker Cache Hit Rate
- 각 모델의 PDF 생성 비용
또한 모든 3D 웹사이트에서 같은 방법으로 인쇄 가능한 문서를 생성할 수 있는 것은 아니다.
실제 3D Scene의 복잡도와 Renderer의 동작, 인쇄 페이지의 요구사항에 따라 달라진다.
이번 글은 브라우저의 3D Renderer와 CSS 인쇄 Layout, Headless Browser, Service Worker를 조합해 하나의 데이터와 렌더링 구조로 온라인 Viewer와 PDF, 오프라인 가이드를 함께 제공하는 방법을 보여주는 실제 개발 사례다.