렌더링 모드

#개요

앱이 완전한 클래스 이름을 언제 알 수 있는지에 따라 렌더링 모드를 선택하세요. 이름이 소스에 보이면 정적 렌더링으로 시작하세요. 완성된 페이지 HTML에서 CSS를 생성하려면 사전 렌더링을, 브라우저에서 만들어지는 새 클래스에는 런타임 렌더링을, 페이지 CSS와 런타임 지원을 결합하려면 점진적 렌더링을 사용하세요.

먼저 프레임워크의 설치 가이드를 완료하세요. 공식 통합이 CSS 진입점을 로드하고 선택한 모드를 구성합니다. 아래 예제는 각 모드의 동작과 검증 방법을 설명합니다. 프레임워크 지원과 처리할 수 있는 HTML은 해당 통합에 따라 다릅니다.

#렌더링 모드 선택하기

대화형 앱도 정적 CSS를 사용할 수 있습니다. 알려진 클래스 전환, CSS 변수 변경, 네이티브 선택자 사용에는 런타임 엔진이 필요하지 않습니다. 완전한 클래스 이름이 빌드 후 처음 알려질 때 런타임 생성을 고려해야 합니다.

사전 렌더링에는 실제 페이지 마크업이 필요합니다. 클라이언트 렌더링 앱의 빈 루트 요소는 서버 렌더러가 처리할 앱 클래스를 제공하지 못합니다. 통합의 경계도 확인하세요. Next.js 점진적 어댑터는 빌드 시점 HTML을 처리하므로 요청 시점 동적 SSR 응답은 브라우저 런타임의 규칙 생성에 의존합니다.

#정적 렌더링

빌드는 소스 텍스트에서 완전한 클래스 문자열을 스캔하고 프로젝트 정의로 CSS를 생성합니다. 앱 코드를 실행하거나 DOM을 관찰하지 않습니다. 브라우저는 Master CSS 런타임 없이 출력 스타일시트를 불러옵니다.

#생성 스타일시트 진입점

앱이 이미 불러오는 스타일시트에서 Master CSS를 가져오세요:

@import '@master/css';

이 import는 생성 유틸리티, 필요한 리소스, 프리셋 기본 스타일의 삽입 지점입니다. 생성 스타일시트 루트마다 하나를 사용하세요. 일반 스타일 규칙 앞의 최상위 import 블록에 유지하세요. 같은 블록의 다른 CSS import는 생성된 Master CSS보다 먼저 출력됩니다.

소스에서 CSS까지의 과정을 보려면 import 뒤에 이 유틸리티 정의를 추가하고 스캔 대상 소스 파일에 버튼을 사용하세요:

@utility btn {  display: inline-flex;  padding-inline: var(--spacing-md);}

<button class="btn text-center">Save</button>

@layer theme {  :root,  :host {    --spacing-md: 1rem  }}@layer utilities {  .btn {    display: inline-flex;    padding-inline: var(--spacing-md)  }  .text-center {    text-align: center  }}

스캐너가 btn과 text-center를 찾습니다. 엔진은 프로젝트 레시피와 프리셋의 고정 유틸리티를 해석한 뒤 규칙과 참조 리소스를 생성합니다. btn 정의만으로는 규칙을 출력하지 않으며 스캔된 클래스나 명시적 안전 목록이 요청해야 합니다.

통합은 일반 앱 소스를 탐색하고 개발 중 CSS를 갱신합니다. 소스에는 완전한 클래스 이름을 유지하고 변하는 값은 CSS 변수로 전달하세요. 클래스 이름 스캔에서 두 방법과 @source, 안전 목록 예외를 다룹니다.

#네이티브 CSS 진입점

CSS 진입점의 네이티브 선택자는 스캔 소스에 해당 클래스가 없어도 기본적으로 유지됩니다. 선택자의 var(--*)와 애니메이션 참조는 일치하는 테마 변수와 키프레임을 유지할 수 있습니다.

프로젝트 소유 네이티브 CSS를 가지치기하려면 pruneNativeCSS: true를, 한 파일만 대상으로 하려면 @prune native;를 사용하세요. @preserve native;는 파일을 통합 수준의 가지치기에서 제외합니다. 사용하지 않는 네이티브 CSS 가지치기를 참고하세요.

모든 빌드 입력과 안전 목록에 p-lg가 없다고 가정한 예제입니다. 동적 값은 클래스 변경 없이 사용자 지정 속성으로 처리할 수 있습니다.

텍스트 설명

정적 빌드는 p-md를 찾아 규칙을 출력합니다. 이후 브라우저 변경이 p-lg를 추가하지만 출력에는 그 규칙이 없습니다.

#런타임 렌더링

시각 편집기나 빌드 후 로드되는 콘텐츠처럼 클래스 이름이 브라우저에서 알려진다면 런타임 렌더링을 사용하세요. 런타임은 MutationObserver로 연결된 요소와 클래스 변경을 추적한 뒤 일치하는 CSS 규칙을 삽입하거나 재사용합니다.

브라우저 엔진이 CSS 규칙을 삽입하거나 재사용합니다. 캐시 규칙은 연결된 DOM의 사용이 끝난 뒤에도 남을 수 있습니다.

텍스트 설명

1. 관찰. 연결된 요소를 읽고 DOM 클래스 변경을 받습니다.
2. 규칙 확보. 컴파일된 프로젝트 프로그램으로 완전한 클래스를 실행합니다.
3. 갱신. 런타임 스타일시트에 네이티브 CSS 규칙을 삽입하거나 재사용합니다.

Vite 런타임 설정처럼 통합을 통해 런타임 모드를 선택하세요. 실행된 뒤 브라우저 콘솔에서 다음 조각을 하나씩 실행하세요:

1. 요소 삽입하기

   const h1 = document.createElement('h1')h1.className = 'text-center'h1.textContent = 'Hello World'document.body.append(h1)

   런타임이 규칙을 생성하면 연결된 제목이 가운데 정렬됩니다.

2. 클래스 추가하기

   h1.classList.add('(font-size:3rem)')

   제목이 3rem으로 커지며 기존 정렬 규칙도 계속 사용됩니다.

3. 클래스 제거하기

   h1.classList.remove('text-center')

   제목이 정렬 규칙에 더 이상 일치하지 않아 상속된 정렬로 돌아갑니다. 런타임이 사용하지 않는 규칙을 일시적으로 유지해도 마찬가지입니다.

4. 요소 제거하기

   h1.remove()

   이 제목은 두 클래스 모두 더 이상 사용하지 않습니다. 다른 연결된 요소도 사용하지 않는다면 유휴 정리 중 규칙을 제거할 수 있습니다.

두 클래스가 함께 있을 때는 다음 규칙을 사용합니다:

@layer utilities {  .text-center {    text-align: center  }  .\(font-size\:3rem\) {    font-size: 3rem  }}

런타임 생성은 JavaScript 시작에 의존합니다. 페이지 초기 규칙이 응답에 이미 있어야 한다면 사전 렌더링 CSS를 사용하고 이후 클래스 이름에 필요할 때만 런타임 지원을 추가하세요.

#런타임 시작 전 페이지 숨기기

런타임 전용 페이지에는 런타임이 생성하기 전까지 규칙이 없습니다. 스타일 없이 그려지지 않도록 루트 요소에 hidden을 추가하세요:

<html lang="en" hidden>  <!-- Load the stylesheet and runtime using your integration's setup. --></html>

런타임은 시작 후 hidden을 제거하며 처리된 시작 오류 경로도 루트를 다시 표시합니다. 하지만 JavaScript가 꺼져 있거나 런타임 스크립트가 차단되거나 다운로드에 실패하면 페이지는 계속 숨겨집니다. 이 경우에도 읽을 수 있어야 하는 콘텐츠에는 정적 또는 사전 렌더링 CSS를 사용하세요. 점진적 페이지는 첫 화면 CSS를 이미 포함하므로 표시 상태를 유지합니다.

#런타임 프로그램 미리 로드하기

엔진이 첫 규칙을 생성하려면 프로그램이 필요합니다. 런타임 전용 페이지에서는 문서 파싱 중 요청을 시작하도록 프로그램을 미리 로드하세요. 동일 출처에서도 as="fetch"와 crossorigin으로 런타임 요청과 일치시키세요:

<!DOCTYPE html><html lang="en" hidden><head>  <link rel="preload" as="fetch" crossorigin href="/master-css/default-program.bin">   <link rel="stylesheet" href="/master-css/base.css">  <script src="/master-css/global.min.js"></script></head></html>

개발자 도구에서 런타임이 다시 요청하지 않고 미리 로드한 응답을 재사용하는지 확인하세요. 일치 조건은 rel="preload"를 참고하세요.

그림은 런타임 전용 페이지와 일치하는 fetch 프리로드를 보여 줍니다. 연결선 길이는 요청 시간이나 시작 속도를 나타내지 않습니다.

텍스트 설명

1. as="fetch"와 일치하는 crossorigin을 가진 프리로드는 문서를 파싱하는 동안 프로그램 요청을 시작합니다.
2. 이 힌트는 엔진을 실행하거나 DOM 클래스를 검사하거나 CSS를 생성하지 않습니다. 런타임 초기화가 일치하는 응답을 사용해 그 작업을 수행합니다.
3. 엔진과 프로그램을 의도적으로 지연하는 점진적 페이지에는 이 프로그램 프리로드를 추가하지 마세요. 페이지 하이드레이션 manifest는 별도 리소스입니다.

#사전 렌더링 — SSG, SSR

빌드나 서버에 최종 페이지 HTML이 있고 이후 클래스에 브라우저 생성이 필요하지 않다면 사전 렌더링을 사용하세요. 서버 렌더러는 HTML을 읽고 규칙을 생성해 style#master-css에 삽입합니다. 마크업에서 CSS를 생성하며 앱 컴포넌트를 HTML로 렌더링하지는 않습니다.

공식 통합은 지원하는 HTML 출력에 이 단계를 수행합니다. 사용자 지정 서버나 빌드 파이프라인을 위한 이 예제는 빌드 통합이 제공하는 virtual:master-css-manifest를 사용합니다. 서버 코드가 실행되기 전에 빌드 도구가 이 가상 모듈을 해석해야 합니다.

<!doctype html><html lang="en"><head>  <meta charset="utf-8">  <meta name="viewport" content="width=device-width, initial-scale=1"></head><body>  <h1 class="font-5xl">Hello World</h1></body></html>

import { readFileSync } from 'node:fs'import { createServerRenderer } from '@master/css-server'import manifest from 'virtual:master-css-manifest'const indexHTML = readFileSync('./index.html', 'utf-8')const renderer = createServerRenderer({ manifest, maxCachedClasses: Infinity })const { html } = renderer.renderHTML(indexHTML)renderer.dispose()

반환된 html을 저장하거나 응답으로 제공하세요. style#master-css에는 제목 규칙과 필요한 font-size 토큰이 포함됩니다:

@layer theme {  :root,  :host {    --font-size-5xl: 2.5rem  }}@layer utilities {  .font-5xl {    font-size: var(--font-size-5xl)  }}

이 출력에는 Master CSS 런타임이나 hydration 매니페스트가 필요하지 않습니다. 나중에만 나타나는 클래스에는 CSS를 따로 제공하거나 런타임을 지원하는 모드가 필요합니다.

유한한 정적 빌드에서는 렌더러가 캐시 규칙을 재사용하면서 페이지별 CSS를 생성할 수 있습니다. 매니페스트가 바뀌면 다시 만들고 빌드가 끝나면 해제하세요. 장기 실행 서버에서는 빌드 예제의 Infinity 대신 상한이 있는 maxCachedClasses를 선택하세요. 서버 API를 참고하세요.

#점진적 렌더링

서버나 빌드가 초기 페이지 CSS를 생성할 수 있고 브라우저가 나중에 새 클래스를 추가할 수 있다면 점진적 렌더링을 사용하세요. 응답은 style#master-css에 CSS를 포함하며 런타임은 페이지 hydration 매니페스트를 읽어 이미 포함된 클래스와 엔진이 필요한 클래스를 구분합니다.

초기 CSS는 HTML과 함께 도착합니다. 유효한 사전 렌더링 스타일시트와 페이지 매니페스트가 있으면 매니페스트 밖의 연결 클래스가 나타날 때까지 엔진을 지연합니다.

텍스트 설명

1. 렌더링. 렌더링된 페이지 HTML의 클래스에서 CSS를 생성합니다.
2. 전달. 초기 CSS를 HTML과 함께 보내 브라우저가 런타임 시작 전에 적용하게 합니다.
3. 후속 처리. 페이지 hydration 매니페스트를 읽고 연결된 DOM 클래스를 추적합니다. 기본적으로 매니페스트 밖의 클래스가 브라우저 엔진과 프로젝트 프로그램을 로드하고 일치하는 기존 규칙을 채택한 뒤 추가 CSS를 생성합니다.

일반적인 출력은 style 요소에서 외부 매니페스트를 가리킵니다:

<style id="master-css" data-master-css-hydration-manifest="/_master-css/hydration/master-css-hydration.<hash>.json">...</style>

실제 에셋 URL은 통합이 제공합니다. 안정적인 JSON 에셋을 게시할 수 없는 사용자 지정 SSR 호스트는 대신 인라인 script#master-css-hydration-manifest를 사용할 수 있습니다. 생성 규칙이나 관리 리소스가 없는 페이지에는 매니페스트 포인터가 필요하지 않습니다.

브라우저는 런타임이나 매니페스트가 로드되기 전에 인라인 CSS를 적용할 수 있습니다. 이는 CSS 사용 가능 시점을 설명하며 실제 페인트 시점은 페이지의 다른 리소스에도 달려 있습니다. 페이지 hydration 매니페스트나 지연된 프로젝트 프로그램을 미리 로드하지 마세요. 미리 로드를 참고하세요.

매니페스트에 나열된 클래스는 엔진을 시작하지 않고 재사용할 수 있습니다. 일반 작성 클래스와 생성 선택자 또는 프로젝트 선택자가 참조하는 자체 규칙 없는 상태·테마 클래스도 포함됩니다. 이미 렌더링된 선택자가 사용하는 속성을 바꾸는 것 역시 새 클래스 규칙이 필요하지 않습니다. 완전한 클래스가 매니페스트에 없다면 프로젝트의 다른 소스에 있었어도 엔진이 시작됩니다.

유효한 사전 렌더링 산출물이 있을 때의 기본 점진적 인계이며 성능 타임라인이 아닙니다.

텍스트 설명

브라우저에 CSS와 유효한 페이지 매니페스트가 있습니다. 알려진 연결 클래스는 기존 CSS를 사용하고 매니페스트 밖의 클래스는 지연 엔진 로드로 분기합니다.

#CSS 하이드레이션

하이드레이션은 런타임이 기존 CSS 규칙을 채택하게 합니다. 시작 시 명시적 hydrationManifest 옵션을 읽거나 인라인 매니페스트 또는 style#master-css의 URL을 찾습니다. 엔진이 지연된 동안에는 스타일시트를 재구성하지 않고 사용 정보를 추적합니다.

엔진이 시작하면 일치 규칙을 채택하고 불일치하면 CSS를 재구성합니다. 참조한 매니페스트를 로드하거나 검증할 수 없으면 비교 전에 시작을 거부합니다.

텍스트 설명

1. 읽기. 페이지 hydration 매니페스트를 불러오고 기존 스타일시트를 계속 사용합니다.
2. 검증. 브라우저 엔진이 시작하면 프로젝트 프로그램으로 매니페스트 클래스를 서버 규칙 순서대로 재실행하고 리소스를 검증하며 생성 규칙과 기존 CSSOM을 비교합니다.
3. 채택 또는 재구성. 일치 규칙을 런타임 관리 규칙 객체로 재사용합니다. 불일치하면 CSS를 재구성합니다.

새 클래스나 cssRuntime.ready()가 엔진을 시작하면 브라우저 엔진은 매니페스트의 클래스를 서버 규칙 순서대로 재실행하고 리소스를 검증한 뒤 생성 결과를 기존 CSSOM과 비교합니다. 일치하는 규칙은 런타임 관리 규칙이 되고 새 클래스가 추가 CSS를 생성할 수 있습니다. 제거된 클래스의 사전 렌더링 규칙은 이 인계까지 남을 수 있으며 이후 일반적인 유지 규칙 정리 경로를 따릅니다.

매니페스트는 리소스 순서와 페이지 스타일시트가 이미 출력한 전역 리소스를 담습니다. CSS 텍스트를 반복하거나 프로젝트 프로그램을 대체하지 않습니다. 같은 빌드의 HTML 및 에셋과 함께 유지하세요.

#통합 지원

다음 공식 어댑터의 기본값은 정적 렌더링입니다. 빌드 시점에 알 수 없는 클래스에는 런타임 생성을 명시적으로 선택합니다. pre-render는 클라이언트 런타임 없이 HTML에서 CSS를 생성하고 progressive는 HTML 렌더링과 후속 클래스용 런타임을 결합합니다. 어댑터가 처리할 수 있는 HTML은 호스트에 따라 다릅니다:

프레임워크가 Vite나 Webpack을 사용한다는 이유만으로 번들러가 서버 동작을 추가할 수는 없습니다. Webpack HTML 삽입도 개발 서버의 정적 디렉터리에서 직접 제공되는 파일을 다시 쓰지 않습니다. Astro 미들웨어는 반환 전에 전체 HTML 응답을 읽고 SvelteKit은 페이지 청크 훅을 사용합니다. 전달 경로는 프레임워크 가이드에 따라 선택하세요. PHP, Rails, CMS, .NET 호스트는 Vite로 에셋을 빌드하고 템플릿에서 불러옵니다. 서버 렌더링 앱을 참고하세요.

#네이티브 가지치기는 별도의 선택

점진적 렌더링은 초기 CSS 전달이나 이후 유틸리티 생성 시점을 바꾸지 않고 네이티브 가지치기를 사용할 수 있습니다. 가지치기에는 알려진 사용 집합과 이를 제공하는 빌드 경로가 필요합니다. 런타임 생성은 전달에서 제거된 임의의 네이티브 선택자를 복원할 수 없습니다. 재현 가능한 비교는 CSS 전달 최적화를 참고하세요.

#선택한 모드 검증하기

개발 환경과 프로덕션 빌드를 모두 테스트하세요. 프로덕션에서 CSS를 사전 렌더링하는 통합도 개발 중에는 런타임 생성을 사용할 수 있습니다.

#실행 중인 스타일시트 검사하기

런타임은 style#master-css를 소유하고 CSSOM을 갱신합니다. 시작 후 요소의 텍스트 내용은 신뢰할 만한 실시간 상태가 아닙니다. 대신 스타일시트의 cssRules를 검사하세요:

const sheet = document.querySelector('style#master-css').sheetconsole.log(sheet.cssRules)

#점진적 시작 진단하기

로드 직후 새 클래스가 나타날 가능성이 높다면 enginePrefetch: 'idle'로 유휴 시간에 엔진을 시작합니다. engine: 'eager'는 start() 중 시작합니다. 두 옵션 모두 기본 지연의 절충을 바꾸므로 페이지의 실제 상호작용에 맞춰 선택하세요.

#상호작용이 많은 화면

한 상호작용이 처음 나타나는 클래스를 많이 추가하면 브라우저는 DOM 변경과 새 스타일시트 규칙을 모두 처리해야 합니다. 편집기, 데이터 그리드, 빌더 등 큰 동적 화면에서는 다음을 따르세요:

• 안정적인 레이아웃, 타이포그래피, 컴포넌트 상태는 공유 클래스로 유지하세요.
• 엔진이 준비되면 화면을 삽입하기 전에 예측 가능한 런타임 클래스를 미리 준비하세요.
• 좌표나 사용자 생성 색상처럼 요소마다 자주 변하는 값에는 CSS 변수나 인라인 스타일을 사용하세요.
• 값마다 별도 생성 클래스가 필요하지 않은 반복 상태에는 네이티브 선택자를 사용하세요.

화면의 예측 가능한 클래스를 미리 준비하려면 MasterCSSRuntime.start()가 반환한 핸들을 사용하세요:

await cssRuntime.ready()cssRuntime.ensureClassRules(['grid', 'gap-md'])

런타임 JavaScript, 프로그램 전달, 초기화, DOM 관찰, CSSOM 작업을 함께 측정하세요. 압축된 JavaScript 크기만으로는 상호작용 비용을 설명할 수 없습니다. 측정과 조건은 벤치마크를 참고하세요.

#사용자 생성 마크업

런타임이 관찰하거나 서버가 렌더링하는 각 클래스는 CSS가 되므로 class 속성은 style 속성만큼 강력합니다. 네이티브 선언, url(), :has() 같은 선택자도 포함됩니다. 댓글, CMS 리치 텍스트, 채팅 메시지처럼 다른 사람이 작성한 마크업을 렌더링한다면 HTML 새니타이저에서 class를 style과 같이 취급하세요. 제거하거나 직접 선택한 클래스만 허용하세요. 클래스 이름 자체가 입력이므로 속성값 이스케이프만으로는 부족합니다.

런타임 상태, 전달 산출물, 사용자 지정 시작 진입점, 엔진 호스트는 runtime, server, engine 패키지를 참고하세요.