feat(theme)!: use named export instead of default export, for circular imports (#1873)

Author: SoonIter

e2e/fixtures/custom-layout-ui-switch/theme/index.tsx

@@ -1,4 +1,3 @@
-import Theme from 'rspress/theme';
 import { Layout as BaseLayout } from 'rspress/theme';
 
 const Layout = () => {
@@ -11,9 +10,5 @@ const Layout = () => {
   );
 };
 
-export default {
-  ...Theme,
-  Layout,
-};
-
+export { Layout };
 export * from 'rspress/theme';

packages/cli/theme.ts

@@ -1,2 +1 @@
 export * from '@rspress/core/theme';
-export { default } from '@rspress/core/theme';

packages/core/src/node/initRsbuild.ts

@@ -27,6 +27,7 @@ import {
   inlineThemeScript,
   isProduction,
 } from './constants';
+import { hintThemeBreakingChange } from './logger/hint';
 import type { RouteService } from './route/RouteService';
 import { initRouteService } from './route/init';
 import { rsbuildPluginDocVM } from './runtimeModule';
@@ -87,6 +88,8 @@ async function createInternalBuildConfig(
     return icon;
   };
 
+  await hintThemeBreakingChange(CUSTOM_THEME_DIR);
+
   const [detectCustomIconAlias, reactCSRAlias, reactSSRAlias] =
     await Promise.all([
       detectCustomIcon(CUSTOM_THEME_DIR),

packages/core/src/node/logger/hint.ts

@@ -0,0 +1,41 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { logger } from '@rsbuild/core';
+import picocolors from 'picocolors';
+import { pathExists } from '../utils';
+
+const THEME_DEFAULT_EXPORT_PATTERN = /export default \{(.*?)\}/m;
+
+/**
+ * breaking change
+ */
+export async function hintThemeBreakingChange(customThemeDir: string) {
+  const fileList = ['index.ts', 'index.tsx', 'index.js', 'index.mjs'];
+  let useDefaultExportFilePath: string | null = null;
+  for (const file of fileList) {
+    const filePath = join(customThemeDir, file);
+    if (await pathExists(filePath)) {
+      const content = await readFile(filePath, { encoding: 'utf-8' });
+      if (THEME_DEFAULT_EXPORT_PATTERN.test(content)) {
+        useDefaultExportFilePath = filePath;
+      }
+    }
+  }
+  if (useDefaultExportFilePath) {
+    logger.warn(
+      `[Rspress] Theme breaking change: The theme/index is now using namedExports instead of defaultExports, please update your config file in ${useDefaultExportFilePath}`,
+      picocolors.red(`
+- import Theme from '@rspress/theme-default';
+- export default {
+-  ...Theme,
+-  Layout,
+- };
+- export * from 'rspress/theme';`) +
+        picocolors.green(`+ import { Layout } from '@rspress/theme-default';
+
++ export { Layout };
++ export * from 'rspress/theme';
+`),
+    );
+  }
+}

packages/core/src/runtime/App.tsx

@@ -12,7 +12,7 @@ import {
   type PageData,
   cleanUrl,
 } from '@rspress/shared';
-import Theme from '@theme';
+import { Layout } from '@theme';
 import React, { useContext, useLayoutEffect } from 'react';
 import { HelmetProvider } from 'react-helmet-async';
 import globalComponents from 'virtual-global-components';
@@ -152,7 +152,7 @@ export function App({ helmetContext }: { helmetContext?: object }) {
 
   return (
     <HelmetProvider context={helmetContext}>
-      <Theme.Layout />
+      <Layout />
       {
         // Global UI
         !hideGlobalUIComponents &&

packages/core/src/runtime/clientEntry.tsx

@@ -1,13 +1,13 @@
 import { BrowserRouter, DataContext, ThemeContext } from '@rspress/runtime';
 import { isProduction } from '@rspress/shared';
+import { setup, useThemeState } from '@theme';
 import { useMemo, useState } from 'react';
 import siteData from 'virtual-site-data';
 import { App, initPageData } from './App';
 
 const enableSSG = siteData.ssg;
 
 // eslint-disable-next-line import/no-commonjs
-const { default: Theme, useThemeState } = require('@theme');
 
 export async function renderInBrowser() {
   const container = document.getElementById('root')!;
@@ -52,5 +52,5 @@ export async function renderInBrowser() {
 }
 
 renderInBrowser().then(() => {
-  Theme.setup();
+  setup();
 });

packages/core/theme.ts

@@ -1,2 +1 @@
 export * from '@rspress/theme-default';
-export { default } from '@rspress/theme-default';

packages/document/docs/en/guide/advanced/custom-theme.mdx

@@ -22,30 +22,27 @@ By default, you need to create a `theme` directory under the project root direct
 You can write the `theme/index.tsx` file as follows:
 
 ```tsx title="theme/index.tsx"
-import Theme from 'rspress/theme';
+import { Layout as BasicLayout } from 'rspress/theme';
 
-const Layout = () => <Theme.Layout beforeNavTitle={<div>some content</div>} />;
+const Layout = () => <BasicLayout beforeNavTitle={<div>some content</div>} />;
 
-export default {
-  ...Theme,
-  Layout,
-};
+export { Layout };
 
 export * from 'rspress/theme';
 ```
 
-On the one hand, you need to export a theme configuration object through `export default`, on the other hand, you need to export all named exported content through `export * from 'rspress/theme'` so as to ensure your theme works fine.
+On the one hand, you need to export a theme configuration object through `export`, on the other hand, you need to export all named exported content through `export * from 'rspress/theme'` so as to ensure your theme works fine.
 
 ### 2. Use slot
 
 It is worth noting that the `Layout` component has designed a series of props to support slot elements. You can use these props to extend the layout of the default theme. For example, change the above `Layout` component to the following form:
 
 ```tsx title="theme/index.tsx"
-import Theme from 'rspress/theme';
+import { Layout as BasicLayout } from 'rspress/theme';
 
 // Show all props below
 const Layout = () => (
-  <Theme.Layout
+  <BasicLayout
     /* Before home hero */
     beforeHero={<div>beforeHero</div>}
     /* After home hero */
@@ -93,11 +90,8 @@ const Layout = () => (
   />
 );
 
-export default {
-  ...Theme,
-  Layout,
-};
-
+export { Layout };
+// re-export
 export * from 'rspress/theme';
 ```
 
@@ -107,29 +101,28 @@ In addition to the slot method, if you want to extend the default theme componen
 as well as other Rspress [built-in components](https://github.com/web-infra-dev/rspress/tree/main/packages/theme-default/src/components)
 
 ```tsx title="theme/index.tsx"
-import Theme, { Search } from 'rspress/theme';
+import { Search as BasicSearch, Layout as BasicLayout } from 'rspress/theme';
 
-// Use slot
-const Layout = () => <Theme.Layout beforeNavTitle={<div>some content</div>} />;
 // Custom Home Page
 const HomeLayout = () => <div>Home</div>;
 // Custom 404 page
 const NotFoundLayout = () => <div>404</div>;
-
-export default {
-  ...Theme,
-  Layout,
-  HomeLayout,
-  NotFoundLayout,
-};
+// Use slot
+const Layout = () => (
+  <BasicLayout
+    beforeNavTitle={<div>some content</div>}
+    HomeLayout={HomeLayout}
+    NotFoundLayout={NotFoundLayout}
+  />
+);
 
 // Custom Search Component
-const MySearch = () => (
+const Search = () => (
   <div className="my-search">
-    <Search />
+    <BasicSearch />
   </div>
 );
-export { MySearch as Search };
+export { Search, HomeLayout, NotFoundLayout };
 // re-export
 export * from 'rspress/theme';
 ```
@@ -172,12 +165,10 @@ function Layout() {
 // The setup function will be called when the page is initialized. It is generally used to monitor global events, and it can be an empty function
 const setup = () => {};
 
+// Export Layout component and setup function
+export { Layout, setup };
 // Export all content of the default theme to ensure that your theme configuration can work properly
 export * from 'rspress/theme';
-
-// Export Layout component and setup function
-// Note: both must export
-export default { Layout, setup };
 ```
 
 Layout component will be used to render the layout of the entire document site, you can introduce your custom components in this component, for example:

packages/document/docs/zh/guide/advanced/custom-theme.mdx

@@ -22,30 +22,27 @@
 你可以使用如下的方式来书写 `theme/index.tsx` 文件:
 
 ```tsx title="theme/index.tsx"
-import Theme from 'rspress/theme';
+import { Layout as BasicLayout } from 'rspress/theme';
 
-const Layout = () => <Theme.Layout beforeNavTitle={<div>some content</div>} />;
+const Layout = () => <BasicLayout beforeNavTitle={<div>some content</div>} />;
 
-export default {
-  ...Theme,
-  Layout,
-};
+export { Layout };
 
 export * from 'rspress/theme';
 ```
 
-一方面你需要通过 `export default` 导出一个主题配置对象，另一方面你需要通过 `export * from 'rspress/theme'` 导出所有具名导出的内容，这样才能保证你的主题配置能够正常工作。
+一方面你需要通过 `export` 导出一个主题配置对象，另一方面你需要通过 `export * from 'rspress/theme'` 导出所有具名导出的内容，这样才能保证你的主题配置能够正常工作。
 
 ### 2. 使用插槽
 
 值得注意的是，`Layout` 组件设计了一系列的 props 支持插槽元素，你可以通过这些 props 来扩展默认主题的布局，比如将上面的 `Layout` 组件改成如下的形式:
 
 ```tsx title="theme/index.tsx"
-import Theme from 'rspress/theme';
+import { Layout as BasicLayout } from 'rspress/theme';
 
 // 以下展示所有的 Props
 const Layout = () => (
-  <Theme.Layout
+  <BasicLayout
     /* Home 页 Hero 部分之前 */
     beforeHero={<div>beforeHero</div>}
     /* Home 页 Hero 部分之后 */
@@ -93,11 +90,8 @@ const Layout = () => (
   />
 );
 
-export default {
-  ...Theme,
-  Layout,
-};
-
+export { Layout };
+// 重导出
 export * from 'rspress/theme';
 ```
 
@@ -107,29 +101,28 @@ export * from 'rspress/theme';
 以及其他 Rspress [内置的组件](https://github.com/web-infra-dev/rspress/tree/main/packages/theme-default/src/components)。比如:
 
 ```tsx title="theme/index.tsx"
-import Theme, { Search } from 'rspress/theme';
+import { Search as BasicSearch, Layout as BasicLayout } from 'rspress/theme';
 
-// 传入插槽
-const Layout = () => <Theme.Layout beforeNavTitle={<div>some content</div>} />;
 // 定制 Home 页面
 const HomeLayout = () => <div>Home</div>;
 // 定制 404 页面
 const NotFoundLayout = () => <div>404</div>;
-
-export default {
-  ...Theme,
-  Layout,
-  HomeLayout,
-  NotFoundLayout,
-};
+// 传入插槽
+const Layout = () => (
+  <BasicLayout
+    beforeNavTitle={<div>some content</div>}
+    HomeLayout={HomeLayout}
+    NotFoundLayout={NotFoundLayout}
+  />
+);
 
 // 定制 Search 组件
-const MySearch = () => (
+const Search = () => (
   <div className="my-search">
-    <Search />
+    <BasicSearch />
   </div>
 );
-export { MySearch as Search };
+export { Search, HomeLayout, NotFoundLayout };
 // 重导出其他部分
 export * from 'rspress/theme';
 ```
@@ -172,12 +165,11 @@ function Layout() {
 // setup 函数，会在页面初始化时调用，一般用来做全局事件的监听，可为空函数
 const setup = () => {};
 
-// 导出默认主题的所有内容，这样才能保证你的主题配置能够正常工作
-export * from 'rspress/theme';
-
 // 导出 Layout 组件和 setup 函数
 // 两者必须导出
-export default { Layout, setup };
+export { Layout, setup };
+// 导出默认主题的所有内容，这样才能保证你的主题配置能够正常工作
+export * from 'rspress/theme';
 ```
 
 这个 Layout 组件会被用来渲染整个文档站点的布局，你可以在这个组件中引入你的自定义组件，比如:

packages/document/theme/index.tsx

@@ -1,5 +1,5 @@
 import { NavIcon } from '@rstack-dev/doc-ui/nav-icon';
-import Theme from 'rspress/theme';
+import { Layout as BasicLayout } from 'rspress/theme';
 import { HomeLayout as BasicHomeLayout } from 'rspress/theme';
 import { ToolStack } from './components/ToolStack';
 import './index.css';
@@ -9,13 +9,8 @@ function HomeLayout() {
 }
 
 const Layout = () => {
-  return <Theme.Layout beforeNavTitle={<NavIcon />} />;
-};
-
-export default {
-  ...Theme,
-  Layout,
-  HomeLayout,
+  return <BasicLayout beforeNavTitle={<NavIcon />} />;
 };
 
+export { Layout, HomeLayout };
 export * from 'rspress/theme';