Next.js에서 Master CSS 설정하기

최상위 app 디렉터리를 사용하는 Next.js App Router 프로젝트에 Master CSS를 추가합니다. Master CSS는 스타일 전달 방식을 제어하며 페이지 HTML의 렌더링 방식은 계속 Next.js가 제어합니다.

#설치

1. #Master CSS 추가하기

   기존 Next.js 프로젝트의 루트에서 설치 프로그램을 실행하세요. 기본값은 정적 모드로, 어댑터가 Next.js 빌드를 위해 생성된 스타일시트를 준비합니다.

   설치 프로그램이 app/globals.css에 추가한 @import '@master/css';를 유지하세요. 어댑터는 이 진입점을 처리하고 소스 스캔으로 생성한 스타일을 제공합니다.

   npm create @master/css@2.0.0 -- --framework nextjs --yes

2. #로드되는 설정 확인하기

   루트 레이아웃에서 전역 스타일시트를 계속 가져오고 기존 프로바이더, 메타데이터, 문서 구조를 유지하세요. 아래 레이아웃은 최소 예제입니다. TypeScript 설정을 사용한다면 비동기 설정 함수에서 통합을 반환하여 비동기 빌드 모드가 설정 로더의 최상위 await를 요구하지 않도록 하세요:

   next.config.ts

   import type { NextConfig } from 'next'import withMasterCSS from '@master/css-next'const nextConfig: NextConfig = {}export default async () => withMasterCSS(nextConfig, { mode: 'static' })

   기존 Next.js 옵션은 nextConfig에 유지하세요.

   app/globals.css

   @import '@master/css';

   app/layout.tsx

   import './globals.css'export default function RootLayout({ children }: { children: React.ReactNode }) {  return <html lang="en"><body>{children}</body></html>}

3. #Master CSS 사용 시작하기

   개발 서버를 시작하고 첫 페이지에 스타일을 적용하세요.

app/page.tsx

export default function Home() {  return (    <p id="master-check" className="w-fit m(0) p-md b-solid b(1) b-line-divider r-md text-sm font-regular bg-surface-raised fg-text-strong">      Hello World    </p>  )}

중립적인 표면, 얇은 테두리, 작은 모서리 반경과 네 면 각각 1rem의 패딩입니다.

#설정 확인하기

npm run dev를 실행하고 페이지의 p-md를 p-lg로 바꾸세요. 안쪽 여백이 1rem에서 1.5rem으로 늘어나야 합니다. 원래대로 돌린 뒤 프로덕션 전달을 확인합니다:

npm run buildnpm run start

JavaScript를 끄고 프로덕션 페이지를 새로고침하세요. 문단의 안쪽 여백, 둥근 모서리, 떠 있는 표면이 유지되어야 합니다. 중첩 라우트도 확인하세요. 루트 레이아웃에서 전역 진입점을 가져오면 애플리케이션 전체에서 CSS를 사용할 수 있습니다.

스타일이 없다면 레이아웃 가져오기와 Next.js가 withMasterCSS()를 포함한 설정을 실제로 불러오는지 확인하세요. 활성 설정 파일은 하나만 유지합니다. src/app을 사용하는 프로젝트에서는 스타일시트 진입점과 레이아웃 경로를 모두 명시적으로 조정하세요. 이 페이지의 설치 레시피는 최상위 app을 대상으로 합니다.

#다른 렌더링 모드 선택하기

기본값은 정적 모드입니다. 설치 프로그램 옵션이 해당 withMasterCSS() 모드를 설정합니다. 모드를 바꿀 때도 전역 스타일시트를 유지하세요:

npm create @master/css@2.0.0 -- --framework nextjs --mode runtime --yes

document.querySelector('#master-check').classList.add('underline')

npm create @master/css@2.0.0 -- --framework nextjs --mode progressive --yes

런타임 또는 점진적 모드의 Turbopack 프로덕션 빌드가 생성된 .master/stylesheets/...-entry.css를 해석할 수 없다고 보고하면 npx next build --webpack으로 Webpack 빌드를 확인하고 배포 전에 npm run start로 결과 페이지를 검증하세요. Webpack 빌드 성공이 Turbopack 경로를 검증하는 것은 아닙니다.

#기존 배포 어댑터 유지하기

프로젝트가 이미 Next.js adapterPath를 사용한다면 nextConfig에 유지한 뒤 그 설정을 withMasterCSS()에 전달하세요. 통합은 설정된 어댑터와 자체 빌드 어댑터를 조합합니다. 명시적인 외부 어댑터 경로가 없으면 NEXT_ADAPTER_PATH로 제공된 배포 어댑터도 인식합니다.

기본적으로 Master CSS가 먼저 실행됩니다. 완성된 HTML을 패키징하는 외부 어댑터는 이후 생성된 CSS와 페이지 매니페스트 참조를 사용할 수 있습니다. 다른 어댑터가 빌드 출력을 먼저 처리해야 할 때만 adapterOrder: 'external-first'를 사용하세요. 프로젝트 옵션과 선택한 모드를 유지하면서 기존 설정 내보내기를 변경합니다:

export default async () => withMasterCSS(nextConfig, {  mode: 'progressive',  adapterOrder: 'external-first'})

두 어댑터를 모두 활성화한 상태로 프로덕션 빌드를 실행하세요. 최종 배포 출력의 사전 렌더링 라우트를 확인한 뒤 실제 제공 응답도 검사합니다. style#master-css가 유지되어야 하며 참조하는 하이드레이션 매니페스트가 배포 URL에서 로드되어야 합니다. 동적 라우트는 별도로 테스트하세요. 어댑터 조합이 Master CSS에 요청 시점 CSS 렌더링을 추가하지는 않습니다.