탐색

새 기능

Next.js와 Master CSS: 점진적 렌더링을 선택할 때

사전 렌더링된 Next.js HTML에서 CSS를 생성하고 이후 class를 브라우저에서 처리하며 동적 SSR의 경계를 이해합니다.

작성자

컴포넌트는 소스에 완전한 문자열로 존재하지 않는 class 이름을 만들 수 있습니다. Next.js가 빌드 중 해당 컴포넌트를 렌더링하면 소스 스캐너가 추론하지 못해도 최종 HTML에는 class가 포함됩니다. @master/css-next의 점진적 렌더링은 이 HTML로 페이지 CSS를 생성하고 이후 브라우저의 새 class는 Master CSS 런타임이 처리하게 합니다.

기본값은 여전히 정적 렌더링입니다. 완전한 class 이름이 소스에 보이고 일반 생성 스타일시트로 충분하다면 정적 모드를 사용하세요. 정적 또는 사전 렌더링 페이지에서 최종 마크업 기반 CSS와 이후 class 변경에 대한 런타임 지원이 필요하면 점진적 모드를 선택하세요.

경계는 빌드 시점의 HTML입니다. 어댑터는 next build의 정적 출력과 사전 렌더링 출력을 처리합니다. 요청 시점에 생성되는 동적 SSR 응답은 처리하지 않으며 점진적 모드에서 해당 응답의 생성 규칙은 브라우저 런타임에 의존합니다.

이 페이지의 내용

#최종 HTML이 유용한 이유

Next.js의 Adapter API는 완료된 빌드 출력을 제공합니다. @master/css-next는 onBuildComplete 훅으로 정적·사전 렌더링 HTML을 찾고 각 문서를 Master CSS 서버 렌더러에 전달합니다.

이 시점에서 페이지는 이미 레이아웃, 컴포넌트, 내용을 마크업으로 합쳤습니다. Master CSS는 앱이 이를 구성한 방식을 추론하지 않고 문서의 class 문자열을 읽을 수 있습니다. Next.js가 빌드 중 해당 HTML을 출력한다면 생성된 마크업과 컴포넌트 변형에 유용합니다.

#Next.js의 점진적 렌더링

인계 과정은 세 부분으로 이루어집니다.

  1. Next.js가 next build 중 정적·사전 렌더링 HTML을 생성합니다.
  2. Master CSS가 각 문서를 읽고 생성 규칙을 style#master-css에 삽입합니다.
  3. 브라우저 런타임은 페이지 manifest가 이미 지원하는 class를 추적합니다. 지원되지 않는 class가 엔진을 시작하면 엔진은 새 규칙을 생성하기 전에 일치하는 규칙을 검증하고 채택합니다.

Next.js 점진적 모드의 경계

사전 렌더링 페이지와 동적 라우트를 따로 검증하세요. 빌드 시점 CSS 지원 범위는 요청 시점 SSR 지원 범위를 입증하지 않습니다.

텍스트 설명
  1. 빌드 시점 HTML. Next.js가 정적 또는 사전 렌더링 HTML을 출력합니다. Master CSS 빌드 어댑터가 생성 CSS를 삽입하고 페이지 hydration 데이터를 제공합니다.
  2. 요청 시점 HTML. 동적 SSR 응답은 빌드 어댑터가 끝난 뒤 생성됩니다. 이 통합은 해당 생성 CSS를 사전 렌더링하지 않으며 점진적 모드에서는 브라우저 런타임이 해당 규칙을 생성합니다.

#CSS와 런타임 인계

생성 규칙이 있는 문서에는 외부 페이지 hydration manifest가 제공됩니다. style 요소가 data-master-css-hydration-manifest로 이를 가리키므로 런타임은 엔진 로드를 지연하면서도 지원하는 class를 추적할 수 있습니다. 엔진이 시작되면 일치하는 CSSOM 규칙을 검증하고 채택합니다. 페이지 manifest 밖의 class를 생성해야 할 때 런타임이 엔진을 로드합니다.

인라인 CSS는 인계 전부터 사용할 수 있습니다. manifest는 지속적인 규칙 관리를 지원하며 브라우저가 문서에 이미 있는 CSS를 적용하는 데 필수는 아닙니다. 전체 전달과 hydration 동작은 렌더링 모드를 참고하세요.

#프로덕션 인계 검증하기

Next.js 설치 가이드에 따라 점진적 모드를 선택하고 CSS 진입점을 로드하세요. 아래 예제는 해당 설정을 전제로 합니다. 설정과 어댑터 조합 옵션은 통합 가이드에 유지합니다.

Next.js가 빌드 중 사전 렌더링하는 페이지를 사용하세요. 다음 절의 <Badge tone="blue" />를 해당 페이지에 놓고 다음을 실행하세요.

npm run buildnpm run start

페이지의 응답 소스를 검사하세요. style#master-css에는 파란 배지의 생성 규칙과 data-master-css-hydration-manifest 참조가 있어야 합니다. 참조된 에셋이 로드되는지도 확인하세요. 실행 중인 DOM만 보지 말고 응답 소스를 사용하세요. 런타임 생성이 빌드 시점 CSS 누락을 숨길 수 있기 때문입니다.

다음으로 클라이언트 상호작용으로 <Badge tone="neutral" />를 추가하세요. 해당 class가 페이지 manifest 밖에 있으면 브라우저 생성이 누락된 규칙을 제공합니다. 두 번째 관찰은 후속 동작을, 초기 응답은 빌드 시점 지원 범위를 검증합니다. 런타임 준비와 복구 경계는 렌더링 모드에 설명되어 있습니다.

#소스 스캔과 렌더링된 class

Master CSS 소스 스캔에는 완전한 class 문자열이 필요하며 컴포넌트 보간을 평가하지 않습니다. 변형을 미리 알고 있다면 모든 완전한 class를 담는 명시적 맵이 적합합니다.

점진적 렌더링은 대신 사전 렌더링 문서에 나타나는 class 이름을 사용할 수 있습니다. 다음 컴포넌트를 살펴보세요.

Badge.tsx
export function Badge({ tone }: {  tone: 'blue' | 'neutral'}) {  return (    <span className={`px-xs py-3xs r-sm bg-${tone}/.1 fg-text-${tone}`}>      New    </span>  )}

<Badge tone="blue" />를 렌더링하면 다음과 같습니다.

blue.html
<span class="px-xs py-3xs r-sm bg-blue/.1 fg-text-blue">New</span>

<Badge tone="neutral" />를 렌더링하면 다음과 같습니다.

neutral.html
<span class="px-xs py-3xs r-sm bg-neutral/.1 fg-text-neutral">New</span>

빌드 시점 HTML에 어느 배지든 있다면 어댑터는 실제 class 목록의 CSS를 생성합니다. 전경 class는 각각 color: var(--color-text-blue)와 color: var(--color-text-neutral)로 해석되며 배경 class는 대응 색상을 불투명도 10%로 사용합니다. 파란 배지만 있는 페이지는 초기 생성 CSS에 neutral 변형 규칙이 필요하지 않습니다. neutral 배지가 나중에 나타나면 런타임이 해당 규칙을 생성할 수 있습니다.

이 선택은 소스 기반 지원 범위를 렌더링된 HTML 지원 범위와 브라우저 런타임으로 바꿉니다. 유한한 class 맵으로 필요한 모든 변형을 제공할 수 있다면 정적 모드가 여전히 적합합니다.

#페이지에서 달라지는 점

#CSS 사용 가능 시점

사전 렌더링 문서는 응답에 생성 CSS를 포함합니다. 이 규칙은 Master CSS 런타임 시작을 기다리지 않고 페이지 스타일에 적용될 수 있습니다. 해당 스타일에 런타임 생성이 선행 조건이 아니게 되지만 첫 페인트 개선이 측정되었다는 뜻은 아닙니다. 이미지, 글꼴, 다른 스타일시트, 스크립트도 렌더링에 영향을 줍니다.

#라우트 단위 CSS 출력

각 문서는 자체 HTML에 필요한 생성 class 규칙을 받습니다. 공유 네이티브 스타일은 여전히 앱의 스타일시트 설정을 따릅니다. 사전 렌더링이 페이지의 모든 스타일이 생성 유틸리티라거나 모든 앱 CSS가 라우트별로 고유하다는 뜻은 아닙니다.

#런타임 유연성 유지

클라이언트 전용 컴포넌트와 이후 class 변경도 계속 지원합니다. 점진적 모드는 런타임과 hydration manifest 전달 비용을 더하므로 모드를 선택할 때 더 단순한 정적 스타일시트와 해당 비용을 비교하세요.

작성 구문은 그대로입니다. 모드는 class를 읽는 시점과 생성 규칙이 페이지에 도달하는 방식을 바꿉니다.

#현재 경계

요청 시점 SSR 응답으로만 존재하는 라우트에는 빌드 어댑터가 처리할 완성된 HTML이 없습니다. 점진적 모드는 해당 응답에 사전 렌더링 CSS를 제공하지 않습니다. 특히 JavaScript 시작 전 스타일이 필요하다면 대표 동적 라우트를 사전 렌더링 페이지와 따로 테스트하세요.

배포 통합도 빌드 출력을 처리한다면 어댑터 조합 설정을 따르고 배포된 응답도 검사하세요. 로컬 빌드가 올바르다고 이후 어댑터가 생성 CSS와 manifest URL을 보존했다는 뜻은 아닙니다.

#정적 렌더링을 유지할 때

소스 스캔이 완전한 class 문자열을 찾을 수 있다면 기본 Next.js 설정을 사용하세요. 정적 모드는 Master CSS 브라우저 런타임 없이 스타일시트를 생성합니다. 선택한 번들러는 따로 검증하세요. 설치 가이드에 현재 생성 에셋의 제약과 Webpack 빌드 경로가 있습니다. 대화형 컴포넌트도 스타일시트에 이미 포함된 class 사이를 전환할 수 있습니다.

최종 빌드 시점 HTML 기반 CSS와 새 class의 런타임 지원이라는 구체적인 필요가 있을 때 점진적 모드를 선택하세요. 앱 전체에 적용하기 전에 사전 렌더링 페이지와 동적 라우트를 모두 검증하세요.