docs: support ssr for improve seo (#1257)

* docs: support ssr for improve seo

* chore: move buildin HomePage to pages for improve SSR

* Update .dumi/pages/index/components/ShowCase/index.tsx

Co-authored-by: thinkasany <[email protected]>

* chore: update vitest for fix ts

* fix: @ant-design/web3-bitcoin ts config

* chore: update config for fix ci

* fix: build doc bug

* fix: home page ssr

* fix: use wagmi alias for fix bug

* chore: update pacakge.json

* chore: fix react version

* chore: revert useless code

* chore: update vitest for fix ci

* fix: remove qurey client config for fix ssr bug

---------

Co-authored-by: tingzhao.ytz <[email protected]>
Co-authored-by: thinkasany <[email protected]>

.dumi/app.tsx

@@ -1,6 +1,8 @@
 import React from 'react';
 import { ConfigProvider } from 'antd';
 
+console.log(`[dumi] build site with React version: ${React.version}`);
+
 export function rootContainer(container: React.ReactNode): React.ReactNode {
   return <ConfigProvider>{container}</ConfigProvider>;
 }

.dumi/theme/builtins/HomePage/components/ShowCase/index.tsx → .dumi/components/ShowCase/index.tsx

@@ -21,7 +21,12 @@ export const ShowCase: React.FC = () => {
     '--theme-text-color': curTheme.name === 'Dark' ? token.colorWhite : token.colorTextBase,
   } as React.CSSProperties;
 
-  const caseList = [<Connect />, <NFTCard />, <PayPanel />, <CryptoInput />];
+  const caseList = [
+    <Connect key="Connect" />,
+    <NFTCard key="NFTCard" />,
+    <PayPanel key="PayPanel" />,
+    <CryptoInput key="CryptoInput" />,
+  ];
 
   return (
     <div className={styles.container} style={themeStyle}>

.dumi/theme/builtins/HomePage/index.tsx → .dumi/pages/index/index.tsx

@@ -4,12 +4,12 @@ import classNames from 'classnames';
 import { usePrefersColor } from 'dumi';
 import SiteContext from 'dumi-theme-antd-web3/dist/slots/SiteContext';
 
-import { Banner } from './components/Banner';
-import { Features } from './components/Features';
-import { ShowCase } from './components/ShowCase';
-import { Theme } from './components/Theme';
-import { FullTheme, themes } from './components/Theme/components/Thumbnail';
-import { ThemeContext } from './components/ThemeContext';
+import { Banner } from '../../components/Banner';
+import { Features } from '../../components/Features';
+import { ShowCase } from '../../components/ShowCase';
+import { Theme } from '../../components/Theme';
+import { FullTheme, themes } from '../../components/Theme/components/Thumbnail';
+import { ThemeContext } from '../../components/ThemeContext';
 import styles from './index.module.less';
 
 export const HomePage: React.FC = () => {

.dumi/theme/SiteThemeProvider.tsx

@@ -1,6 +1,6 @@
 import React, { useEffect } from 'react';
 import { theme as antdTheme, ConfigProvider, type ThemeConfig } from 'antd';
-import { ThemeProvider, useTheme, type ThemeProviderProps } from 'antd-style';
+import { ThemeProvider, type ThemeProviderProps } from 'antd-style';
 
 interface NewToken {
   bannerHeight: number;

.dumi/theme/builtins/ThemeEditorPage/index.tsx

@@ -14,7 +14,13 @@ const ANT_DESIGN_WEB3_CUSTOM_THEME = 'ant-design-web3-custom-theme';
 const ThemeEditorPage: React.FC = () => {
   const [messageApi, contextHolder] = message.useMessage();
   const initialThemeConfigRef = React.useRef(
-    parseThemeConfig(JSON.parse(localStorage.getItem(ANT_DESIGN_WEB3_CUSTOM_THEME) || '{}')),
+    parseThemeConfig(
+      JSON.parse(
+        (typeof localStorage !== 'undefined' &&
+          localStorage.getItem(ANT_DESIGN_WEB3_CUSTOM_THEME)) ||
+          '{}',
+      ),
+    ),
   );
   const locale = useLocale();
   const token = useTheme();

.dumi/theme/layouts/GlobalLayout.tsx

@@ -1,6 +1,7 @@
 import React from 'react';
+import { createCache, extractStyle, StyleProvider } from '@ant-design/cssinjs';
 import { en_US, Web3ConfigProvider, zh_CN } from '@ant-design/web3-common';
-import { useIntl, useLocation, useOutlet, usePrefersColor } from 'dumi';
+import { useIntl, useLocation, useOutlet, usePrefersColor, useServerInsertedHTML } from 'dumi';
 import { GlobalLayout as ThemeGlobalLayout } from 'dumi-theme-antd-web3';
 
 import SiteThemeProvider from '../SiteThemeProvider';
@@ -11,15 +12,28 @@ const GlobalLayout: React.FC = () => {
   const [color] = usePrefersColor();
   const { locale } = useIntl();
 
+  // 参考 antd 服务端渲染文档 https://ant-design.antgroup.com/docs/react/server-side-rendering-cn#%E5%86%85%E8%81%94%E6%A0%B7%E5%BC%8F
+  // https://github.com/ant-design/ant-design/blob/a4c884cb3d0ddc3560801e851d3cbf363de686dd/.dumi/theme/layouts/GlobalLayout.tsx#L217
+  const [cssCache] = React.useState(() => createCache());
+
+  useServerInsertedHTML(() => {
+    const styleText = extractStyle(cssCache, { plain: true });
+    return <style id="antd-cssinjs" dangerouslySetInnerHTML={{ __html: styleText }}></style>;
+  });
+
   return (
-    // @ts-ignore ts props error in dumi theme
-    <ThemeGlobalLayout>
-      <Web3ConfigProvider locale={locale === 'zh-CN' ? zh_CN : en_US}>
-        <SiteThemeProvider themeMode={color || 'auto'}>
-          <div className={pathname === '/' || pathname === '/index-cn' ? 'home' : ''}>{outlet}</div>
-        </SiteThemeProvider>
-      </Web3ConfigProvider>
-    </ThemeGlobalLayout>
+    <StyleProvider cache={cssCache}>
+      {/*@ts-ignore */}
+      <ThemeGlobalLayout>
+        <Web3ConfigProvider locale={locale === 'zh-CN' ? zh_CN : en_US}>
+          <SiteThemeProvider themeMode={color || 'auto'}>
+            <div className={pathname === '/' || pathname === '/index-cn' ? 'home' : ''}>
+              {outlet}
+            </div>
+          </SiteThemeProvider>
+        </Web3ConfigProvider>
+      </ThemeGlobalLayout>
+    </StyleProvider>
   );
 };
 

.dumirc.ts

@@ -1,7 +1,9 @@
 import { existsSync, readdirSync } from 'fs';
-import { join } from 'path';
+import { join, resolve } from 'path';
 import { defineConfig } from 'dumi';
 
+const openSSR = process.env.SSR || process.env.NODE_ENV === 'production';
+
 // utils must build before core
 // runtime must build before renderer-react
 const pkgList = readdirSync(join(__dirname, 'packages'))
@@ -34,7 +36,14 @@ const alias = pkgList.reduce(
 
     return pre;
   },
-  {} as Record<string, string>,
+  (openSSR
+    ? {
+        // 打开 SSR 的情况下需要配置 wagmi 的别名，因为安装了 18.3.0-canary-c3048aab4-20240326 版本的 react 会导致文档 demo 和 packages 中依赖不同版本的 wagmi（pnpm 的包管理机制的原因），导致出现类似下面这样的错误
+        // `useConfig` must be used within `WagmiProvider`. Docs: https://wagmi.sh/react/api/WagmiProvider.html Version: [email protected]
+        wagmi: resolve('./node_modules/wagmi'),
+        '@tanstack/react-query': resolve('./node_modules/@tanstack/react-query'),
+      }
+    : {}) as Record<string, string>,
 );
 
 export default defineConfig({
@@ -52,6 +61,16 @@ export default defineConfig({
     gtag('config', 'G-C31HWEY1D4');
     `,
   ],
+  ssr: openSSR
+    ? {
+        // for improve seo
+        // 需要使用 React 18.3.0-canary-c3048aab4-20240326 版本，因为 umi 是基于整个 HTML 做的水合，在 18.3.1 版本有 bug，会导致浏览器插件的内容影响水合
+        // 在 pnpm run build:docs 修改 react 版本，不能在依赖中直接修改，一方面是为了组件开发环境尽可能和用户环境一致，另外一方面是为了避免 vitest 使用多个版本的 React 情况下报错
+        // config useStream to false, 否则会导致 html 不是直接插入到 root 中的
+        // 本地开发关闭 SSR，因为本地使用的是 18.3.1 版本，打开会因为水合失败报错，如果要调试，可以临时安装 React 18.3.0-canary-c3048aab4-20240326 版本，然后打开 ssr 调试
+        useStream: false,
+      }
+    : false,
   mfsu: false,
   alias,
   metas: [

.gitignore

@@ -1,6 +1,7 @@
 node_modules
 coverage
 dist
+/server
 
 .umi
 .umi-test

package.json

@@ -24,9 +24,10 @@
   "scripts": {
     "start": "dumi dev",
     "dev": "dumi dev",
+    "dev:ssr": "cross-env SSR=1 dumi dev",
     "dev:lib": "pnpm run --parallel --if-present --recursive --filter \"@ant-design/*\" dev",
     "build": "pnpm run --if-present --recursive --filter \"@ant-design/*\" build",
-    "build:docs": "dumi build",
+    "build:docs": "pnpm i [email protected] [email protected] -w && dumi build",
     "example:ethers": "pnpm run --filter \"@example/ethers\" dev",
     "example:ethers-v5": "pnpm run --filter \"@example/ethers-v5\" dev",
     "example:eth-web3js": "pnpm run --filter \"@example/eth-web3js\" dev",
@@ -76,7 +77,7 @@
     "@types/react-copy-to-clipboard": "^5.0.7",
     "@types/react-dom": "^18.3.1",
     "@umijs/fabric": "^4.0.1",
-    "@vitest/coverage-v8": "^2.0.5",
+    "@vitest/coverage-v8": "^2.1.5",
     "babel-plugin-add-import-extension": "^1.6.0",
     "babel-plugin-inline-react-svg": "^2.0.2",
     "babel-plugin-react-inline-svg-unique-id": "^1.5.0",
@@ -93,8 +94,8 @@
     "rimraf": "^6.0.1",
     "ts-node": "^10.9.2",
     "typescript": "^5.6.2",
-    "vite-plugin-svgr": "^4.2.0",
-    "vitest": "~2.0.5"
+    "vite-plugin-svgr": "^4.3.0",
+    "vitest": "~2.1.5"
   },
   "ci": {
     "type": "aci",
@@ -110,12 +111,12 @@
     "@ant-design/icons": "^5.5.1",
     "@ant-design/web3": "workspace:*",
     "@ant-design/web3-assets": "workspace:*",
+    "@ant-design/web3-bitcoin": "workspace:*",
     "@ant-design/web3-common": "workspace:*",
     "@ant-design/web3-ethers": "workspace:*",
     "@ant-design/web3-icons": "workspace:*",
     "@ant-design/web3-solana": "workspace:*",
     "@ant-design/web3-sui": "workspace:*",
-    "@ant-design/web3-bitcoin": "workspace:*",
     "@ant-design/web3-ton": "workspace:*",
     "@ant-design/web3-wagmi": "workspace:*",
     "@mysten/dapp-kit": "^0.14.11",
@@ -130,7 +131,7 @@
     "antd-token-previewer-web3": "^2.0.8",
     "cross-env": "^7.0.3",
     "decimal.js": "^10.4.3",
-    "dumi": "^2.4.12",
+    "dumi": "^2.4.13",
     "dumi-theme-antd-web3": "0.4.3",
     "ethers": "^6.13.4",
     "github-contributors-lists": "^1.0.3",

packages/web3/src/address/__tests__/index.test.tsx

@@ -1,8 +1,11 @@
+import React from 'react';
 import { fireEvent, render } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
 
 import { Address } from '..';
 
+console.log(`get React version: ${React.version}`);
+
 describe('Address', () => {
   it('mount correctly', () => {
     expect(() => render(<Address />)).not.toThrow();

packages/web3/src/ethereum/demos/custom-wallet.tsx

@@ -30,7 +30,7 @@ const App: React.FC = () => {
                 return {
                   id: 'testWallet',
                   name: 'TestWallet',
-                  provider: window.ethereum,
+                  provider: typeof window !== 'undefined' && window.ethereum,
                 };
               },
             });

packages/web3/src/ethereum/demos/siwe/sign-btn.tsx

@@ -38,7 +38,7 @@ export default function App() {
         domain: window.location.hostname,
         address,
         statement: 'Sign in with Ethereum',
-        uri: window.location.origin,
+        uri: typeof window !== 'undefined' ? window.location.origin : '',
         version: '1',
         chainId: Mainnet.id,
         nonce,

packages/web3/src/sui/demos/query-client.tsx

@@ -5,16 +5,10 @@ import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persist
 import { QueryClient } from '@tanstack/react-query';
 import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';
 
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      gcTime: 1_000 * 60 * 60 * 24, // 24 hours
-    },
-  },
-});
+const queryClient = new QueryClient();
 
 const persister = createSyncStoragePersister({
-  storage: window.localStorage,
+  storage: typeof window !== 'undefined' ? window.localStorage : undefined,
 });
 
 const App: React.FC = () => {