Rspress 2.0 출시: 경험과 AI를 위한 새로운 업그레이드

우리는 Rspress 2.0의 공식 출시를 기쁜 마음으로 발표합니다!

Rspress는 Rsbuild를 기반으로 한 정적 사이트 생성기로, 개발자를 위해 설계된 문서 사이트 도구입니다. 2023년 공식 출시 이후, Rspress 1.x는 총 144개의 버전이 반복되었고, 125명의 기여자가 프로젝트 개발에 참여했습니다. 점점 더 많은 개발자들이 Rspress를 선택하여 효율적인 컴파일 성능, 약속된 라우팅 및 컴포넌트 라이브 미리보기 등의 기능을 활용하여 아름답고 신뢰할 수 있는 문서 사이트를 구축하고 있습니다.

커뮤니티의 피드백과 제안을 바탕으로, Rspress 2.0은 테마 미적 요소, AI-native, 문서 개발 경험, Rslib와 함께 사용 등 여러 면에서 한층 더 발전했습니다.

왜 Rspress 2.0인가

Rspress 1.x는 문서 사이트 프레임워크의 컴파일 성능 문제를 해결했지만, 여전히 문서 개발 도구로서의 핵심 경험에 영향을 미치는 몇 가지 문제가 남아 있었습니다. 2.0 버전은 컴파일 성능에 대한 추구를 넘어 문서 사이트 경험의 다른 측면에도 집중하고 있습니다:

• 테마 스타일: 더 아름다운 기본 테마 세트를 제공하며, 다양한 사용자 정의 테마 방식을 제공하여 1.x에서 테마 사용자 정의에 안정적인 API가 부족했던 문제를 해결했습니다.
• AI-native: 문서는 단순히 인간 독자를 위한 것이 아니라, 에이전트가 더 잘 이해하고 사용할 수 있도록 해야 합니다. Rspress는 이제 llms.txt 생성 및 SSG에서 파생된 SSG-MD 기능을 내장하여, 에이전트가 읽을 수 있는 고품질 Markdown 렌더링 콘텐츠를 생성합니다.
• 필요에 따라 컴파일, 즉시 시작: 기본적으로 lazyCompilation을 활성화하고, 링크 호버 시 리소스의 preload 기능과 결합하여 특정 라우트를 방문할 때만 필요한 파일을 구축하여, 프로젝트 규모에 관계없이 dev가 즉시 시작할 수 있도록 합니다.
• Shiki 코드 하이라이트: 기본적으로 Shiki를 통합하여 빌드 시 구문 하이라이트를 완료하며, 테마 전환, transformer 확장(예: @rspress/plugin-twoslash)을 지원하여 더 풍부한 코드 블록 표시 효과를 제공합니다.
• 문서 개발 경험: nav.json, meta.json 등의 파일에 대한 HMR을 최적화하고 IDE 내 코드提示을 위한 json schema를 추가했습니다; 기본적으로 죽은 링크 검사 기능을 활성화했습니다; 외부 파일을 참조할 수 있는 파일 코드 블록 구문을 추가했습니다; @rspress/plugin-preview 및 @rspress/plugin-playground가 동시에 사용될 수 있도록 지원합니다.
• Rslib 통합: 이제 create-rslib를 사용하여 컴포넌트 라이브러리 프로젝트를 생성할 때 Rspress를 문서 도구로 선택하여 컴포넌트 문서 사이트를 빠르게 구축할 수 있습니다.

2.0 새로운 기능

완전히 새로운 테마

2.0 기본 테마는 시스템적인 업그레이드를 맞이하였으며, 팀 디자이너 @Zovn Wei가 전체적으로 디자인하였습니다. 시각적 효과와 읽기 경험 모두에서 큰 폭으로 향상되었으며, 각 컴포넌트는 독립적으로 교체할 수 있어 높은 사용자 정의성을 가지고 있습니다.

테마 사용자 정의

사용자 정의 정도에 따라 낮은 것부터 높은 것까지 CSS 변수, BEM 클래스 이름, ESM 재수출 오버라이드, 컴포넌트 eject의 네 가지 사용자 정의 테마 방식을 제공합니다.- CSS 변수: 새로운 테마는 더 많은 CSS 변수를 노출하여 테마 색상, 코드 블록, 홈 페이지 등의 스타일을 덮어씁니다. CSS 변수 페이지에서 모든 CSS 변수를 인터랙티브하게 미리 보고 조정할 수 있으며, 만족스러운 구성을 찾은 후 프로젝트에 직접 복사하여 사용할 수 있습니다.

• BEM 클래스 이름: 내장 컴포넌트는 이제 모두 BEM 명명 규칙을 따릅니다. 이는 매우 구식의 선택이지만, 또한 우리가 깊이 고민한 결정입니다. 사용자는 CSS 선택기를 통해 스타일을 정확하게 조정할 수 있으며, HTML 구조가 더욱 명확해집니다.
• ESM 재수출 덮어쓰기: CSS에서의 수정이 사용자 정의 요구를 충족하지 못할 경우, JS를 통해 더 깊이 있는 사용자 정의가 가능합니다. theme/index.tsx에서 ESM 재수출을 활용하여 Rspress의 내장 컴포넌트를 덮어쓸 수 있습니다.
• 컴포넌트 이젝트: 새로운 rspress eject [component] 명령을 사용할 수 있으며, 이 명령은 지정된 컴포넌트의 소스 코드를 theme/components/ 디렉토리로 복사합니다. 이 코드를 자유롭게 수정할 수 있으며, 심지어 AI에게 직접 수정하도록 맡겨 깊이 있는 사용자 정의를 실현할 수 있습니다.

내비게이션 바, 사이드바 태그

Rspress 2.0은 태그 컴포넌트를 구현하여 이제 frontmatter의 tag 속성을 사용하여 사이드바나 내비게이션 바에서 UI 주석을 달 수 있습니다.

내장 다국어 지원

1.x 버전에서는 Rspress가 영어 텍스트만 내장했으며, 다른 언어(예: zh)를 사용할 경우 모든 텍스트를 구성해야 하므로 사용이 다소 번거로웠습니다. 이제 2.0 테마는 zh, en, ja, ko, ru 등 여러 언어의 번역 텍스트를 내장하고 있으며, 시스템은 언어 구성에 따라 자동으로 "트리 쉐이킹"을 수행하여 사용 중인 텍스트와 언어만 패키징합니다.

llms.txt 지원

Rspress는 이제 llms.txt 생성 기능을 core에 통합하고 새로운 SSG-MD(정적 사이트 생성을 위한 Markdown, Static Site Generation to Markdown) 기능을 구현했습니다.

React 기반의 동적 렌더링 프레임워크에서는 종종 정적 정보를 추출하기 어려운 문제가 발생하며, Rspress도 동일한 도전에 직면해 있습니다. Rspress는 사용자가 MDX 조각, React 컴포넌트, Hooks 및 TSX 라우팅과 같은 동적 기능을 통해 문서의 표현력을 강화할 수 있도록 허용합니다. 그러나 이러한 동적 콘텐츠를 Markdown 텍스트로 변환할 때 다음과 같은 문제가 발생합니다:

• MDX를 AI에 직접 입력하면 많은 코드 구문 노이즈가 포함되고 React 컴포넌트 내용이 손실됩니다.
• HTML을 Markdown으로 변환하면 종종 효과가 좋지 않으며, 정보 품질을 보장하기 어렵습니다.

이 문제를 해결하기 위해 Rspress 2.0은 SSG-MD 기능을 도입했습니다. 이는 정적 사이트 생성(SSG)과 유사한 새로운 기능이지만, HTML 파일이 아닌 Markdown 파일로 페이지를 렌더링하고 llms.txt 및 llms-full.txt 관련 파일을 생성합니다.

Shiki 컴파일 시 코드 블록 하이라이트Rspress 2.0은 기본적으로 Shiki를 사용하여 코드 하이라이팅을 수행합니다. 1.x의 prism 런타임 하이라이팅 솔루션과 비교하여, Shiki는 컴파일 시 하이라이팅 처리를 완료합니다.

- 다양한 테마 스타일을 지원하며, CSS 변수 페이지에서 서로 다른 Shiki 테마를 인터랙티브하게 전환하고 미리 볼 수 있습니다.
- 또한 Shiki는 twoslash와 같은 사용자 정의 변환기를 사용하여 작성을 풍부하게 확장할 수 있도록 허용합니다.
- 필요에 따라 프로그래밍 언어를 가져와서 런타임 오버헤드와 패키지 크기를 증가시키지 않습니다.
- TextMate 문법을 기반으로 VS Code와 일치하는 정확한 문법 하이라이팅을 구현합니다.

### 빌드 성능 향상

Rspress 2.0은 Rsbuild와 Rspack 2.0 프리뷰 버전으로 구동되며, 기본적으로 필요에 따라 컴파일 및 지속적인 캐시를 활성화합니다.

#### 필요에 따라 컴파일

기본적으로 dev.lazyCompilation이 활성화되어 있으며, 특정 페이지에 접근할 때만 해당 페이지가 컴파일됩니다. 이는 개발 시작 속도를 크게 향상시키며, 심지어 밀리초 수준의 콜드 스타트를 구현합니다. Rspress는 또한 라우팅의 preload 전략을 구현하여, 링크 위에 마우스를 올리면 대상 라우트 페이지를 미리 로드하여 lazyCompilation과 함께 손실 없는 개발 경험을 제공합니다.



#### 지속적인 캐시

2.0은 기본적으로 지속적인 캐시를 활성화하여, 핫 스타트 중에 이전 컴파일 결과를 재사용하여 30%-60%의 빌드 속도를 향상시킵니다. 이는 rspress dev 또는 rspress build를 처음 실행한 후, 이후 시작 속도가 눈에 띄게 향상됨을 의미합니다.

### 문서 개발 경험

#### 기본적으로 죽은 링크 검사 활성화

Rspress 2.0은 기본적으로 죽은 링크 검사 기능을 활성화합니다. 빌드 과정에서 문서 내의 유효하지 않은 링크를 자동으로 감지하여, 이를 통해 신속하게 발견하고 수정할 수 있도록 도와줍니다.



#### 파일 코드 블록

file="./path/to/file" 속성을 사용하여 외부 파일을 코드 블록의 내용으로 참조할 수 있으며, 예제 코드를 별도의 파일에 두어 관리할 수 있습니다.

#### preview의 더 유연한 meta 사용법

@rspress/plugin-preview는 이제 meta 속성을 기반으로 사용되며, 더 유연해졌고 파일 코드 블록과 함께 사용할 수 있습니다.



### Rslib & Rspress

create-rslib를 사용하여 프로젝트를 생성할 때, 이제 Rspress 도구를 선택할 수 있습니다. 이를 통해 컴포넌트 라이브러리를 개발하는 동시에, 컴포넌트 사용 설명서, API 참조를 전시하거나 컴포넌트 효과를 실시간으로 미리 볼 수 있는 문서 사이트를 신속하게 구축할 수 있습니다.

### 더 많은 Rspress 공식 플러그인

Rspress 2.0은 여러 공식 플러그인을 추가했습니다:

- @rspress/plugin-algolia: Rspress의 내장 검색을 Algolia DocSearch로 교체 지원
- @rspress/plugin-twoslash: TypeScript 코드 블록에 타입 힌트를 추가
- @rspress/plugin-llms: SSG 및 SSG-MD를 지원하지 않는 프로젝트에 llms.txt 생성 기능 제공
- @rspress/plugin-sitemap: SEO 최적화를 위한 Sitemap 파일 자동 생성

## 주요 변경 사항

### Rspress 1.x에서 마이그레이션

1.x 프로젝트의 사용자라면, 1.x에서 2.0으로 업그레이드하는 데 도움이 되는 자세한 마이그레이션 문서를 준비했습니다. 페이지 내의 "Markdown 복사" 기능을 직접 사용하여, 이를 자주 사용하는 코드 에이전트(예: Claude Code 등)에 입력하여 마이그레이션을 완료할 수 있습니다.### Node.js와 상위 의존성 버전 요구 사항

Rspress 2.0은 Node.js 버전 20+ 및 React 버전 18+를 요구합니다.

다음 단계

Rspress 2.0의 출시는 새로운 시작일 뿐입니다. 이번 출시 이후 Rspress는 지속적으로 발전할 것입니다:

• 생태계 통합 추진: Rslib, Rstest와 더 깊이 결합하여 프론트엔드 프로젝트와 컴포넌트 라이브러리 프로젝트의 통합 개발 경험을 제공합니다.
• AI와 문서의 더 깊은 통합 탐색: 예를 들어, 스마트 Q&A, 자동 요약 등; SSG-MD를 완성하여 안정적이고 더 사용하기 쉽게 만듭니다.

지금 바로 Rspress 2.0을 사용하거나 업그레이드하여 새로운 문서 개발 여정을 경험하세요!

npm create rspress@latest